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Chapter 1 


Looking at the Basics 


BASICO9 is a computer language created for use with the OS-9 
operating system. Along with standard BASIC language state- 
ments and functions, it includes the most useful elements of the 
PASCAL computer language. 


In brief, BASIC09’s advantages are: 


Fast execution speed 


Full feature editing 


Modular 
programming 
functions 


Interfacing to OS-9 


Structured 
programming 


BASICO9 compiles procedure lines as 
you enter them. When you finish a 
procedure, you can compile it further. 
The result? Procedures that execute 
nearly as fast as machine language. 


The text editor features automatic line 
formatting, search, search and change, 
global search, global search and 
change, line renumbering, and much 
more. You can move in and out of the 
editor quickly and easily. 


You can write small, easy-to-under- 
stand procedures, then chain them to 
create sophisticated programs. You can 
call one procedure from another, 
regardless of whether the called proce- 
dure is in memory or on disk. 


Both you and your procedures can 
take advantage of almost any OS-9 
function from within BASIC, including 
the execution of disk management 
commands and application programs. 


You can structure procedures more 
efficiently and clearly by taking advan- 
tage of a variety of loop commands, 
optional line numbering, and 
BASIC09’s ability to call modules 
written in other computer languages. 
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Memory saving 
features 


Complex data 
structures 


Sophisticated 
graphics 


High speed, 
precision math 


Simple and fast 
debugging 


Using BASIC09 


Strings can be any length. For each 
operation, you can select the most effi- 
cient of five available data types. Com- 
piled procedures use less space. You 
can save several procedures into one 
file. 


Combine any type of data into a single 
dimensioned data structure that you 
can move, store, and assign easily and 
quickly. 


BASICO9 has three levels of graphics. 
The high resolution graphics and text 
capabilities feature more than 50 
functions. 


BASICO9 has a full range of fast and 
accurate math and transcendental 
capabilities including powers, roots, 
trigonometry, logic, and Boolean 
functions. 


BASICO9 provides superior debugging 
functions. It checks syntax as you 
enter lines. It points to the location of 
your errors and tells you what they 
are. You can stop programs, enter the 
debugger, then continue execution. 
Execution errors automatically put you 
in a debugging mode where you can 
examine values, and step and trace 
your way through faulty procedures. 


Before anything else, make a backup copy of your BASIC09/ 
CONFIG diskette. You can do this using the BACKUP command. 
If you are not familiar with BACKUP, see Chapter 3 of Getting 


Started With OS-9. 


To use BASICO9, boot your computer as described in Getting 
Started With OS-9. Replace the system diskette in Drive /D0 
with the BASICO9/CONFIG backup diskette and type: 


basic@9Q | ENTER 
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After a short pause, during which OS-9 loads BASICO9 from the 
diskette, the screen displays the copyright and a new prompt, 
like this: 


BASIC#S 
RS VERSION 01.00.91 
COPYRIGHT 1988 BY MOTOROLA INC. 
AND MICROWARE SYSTEMS CORP. 
REPRODUCED UNDER LICENSE 
TO TANDY CORP. 
ALL RIGHTS RESERVED 


Basicd9 
Ready 
Bs 


The B: indicates that your computer is in the BASICO9 command 
mode. From the command mode, you can issue instructions to 
the system executive to manipulate procedures (programs). 


Requesting More Memory 


Unless you specify otherwise, BASICO9 automatically sets aside 
8192 bytes of memory as a workspace into which you can type or 
load procedures. BASICO9 reserves approximately 1200 bytes of 
the workspace for internal use, leaving you with 6992 bytes for 
workspace. 


There are two ways to set aside more memory for BASICO9 
operations: 


@ You can reserve extra memory when you first enter 
BASICO9 by using the OS-9 memory size option. For 
instance, to reserve 18,176 bytes, enter this command to 
initialize BASICO9: 


basic#9 #18k 


@ You can also request additional memory after loading 
BASICO9. At the command prompt, B:, type: 


mem 180990 (ENTER ] 


This tells BASICO9 to set aside a total of 18,000 bytes of 
memory, if they are available. 
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In both cases, because BASICO9 rounds the amount you request 
to the next multiple of 256, the actual reserved memory is 18176 
bytes. 


Note: If your system does not have enough free memory to 
reserve the amount you specify, the workspace size does not 
change. 


You can also use the MEM command to reduce memory. How- 
ever, BASICO9 does not reduce the size of the workspace if doing 
so destroys resident procedures. 


Writing Procedures 


BASICO9 is a modular programming language. Several proce- 
dures can occupy memory at the same time. Each procedure per- 
forms a particular function but can also interact with others to 
form a sophisticated program. 


To create or change procedures, enter the edit mode by typing 
either edit or at the B: prompt. From now on, 
when directing you to enter the edit mode, this manual uses the 
easier to type (E] command. 


Each time you type a procedure line and press (ENTER), the editor 
checks for common errors. This automatic checking lets you 
catch mistakes before you run the program, saving you testing 
and rewriting time. You can even let the automatic checking 
help you learn the rules of BASICO9. If you are not sure about a 
syntax, go ahead and type it the way you think is correct. If you 
guess wrong, BASICO9 shows where the error is and displays a 
message to tell what is wrong. 


BASIC09’s use of modules lets you divide large and complex proj- 
ects into smaller, easily manageable sections. Not only are the 
smaller procedures easier to write and understand, they are also 
easier to test. As well, because BASICO9 lets you call procedures 
that are outside the workspace (the computer's memory where 
you write and edit procedures), you can accumulate libraries of 
procedures to incorporate into future programs. 


You can work on a program’s procedures either individually or 
as a group. For example, to work on the procedures as a group, 
save your workspace procedures into a single disk file. When you 
subsequently load the file, BASICO9 automatically loads all of 
the procedures. 
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Modules of Other Languages 


BASICO9 can incorporate procedures from other languages, such 
as Pascal, C, or assembly language. Several users can then share 
the procedures. 


Executing Procedures 


You execute or run programs from the command mode. When 
you enter a procedure, BASICO9 compiles it. This means that the 
procedure is ready for execution as soon as you exit the edit 
mode. For instance, if you create a program named Greeting, 
you can execute it by typing from the command mode: 


run greeting ENTER 


Leaving BASIC09 


There are two ways you can exit from BASICO9: 
e At the B: prompt, type: 
bye 


@ Or, at the B: prompt, press (CTRL ][ BREAK]. 


When you use either method, the OS-9 prompt appears immedi- 
ately indicating that the operating system is waiting for a 
command. 


Note: When you exit BASICO9, you lose all procedures 
residing in the workspace. Be sure to save them on disk 
before leaving BASICO9. 


The Keyboard and BASIC09 


You can use some keys and key sequences to produce special 
characters and to accomplish special BASICO9 functions. You ini- 
tiate a key sequence by pressing one key and holding it down 
while pressing a second key. The following list summarizes your 
keyboard’s special functions: 
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ALT 


or 
(cTRL JLE 


or 


(oral }(_) 
(oTrt JC, J 
(oTrL JC. ) 


or 


(cTRL |(9} 


Produces graphic characters. Press char 
where char is a keyboard character). 


A control key that you use with other keys. 
(See below.) 


Stops the current program execution and 
returns to the B: prompt in BASICO09’s com- 
mand mode. 


Moves the cursor back one space. 


Produces an underscore character. 
Produces a left brace ({). 
Produces a right brace (+). 
Produces a tilde (~). 

Produces a backslash (\). 


Performs an ESCAPE function and sends an 
end-of-file message to a program receiving 


keyboard input. To be recognized, 
must be the first thing typed on a line. 


Stops execution of a program and causes 
BASICO09 to enter the Debug mode. 


Displays the next window. 
Displays the previous window. 


Deletes the current line. 


Activates or deactivates the shift lock function. 
Produces a vertical bar (| ). 

Produces an up arrow (4). 

Produces a left bracket ({). 

Produces a right bracket (1). 
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Redisplays the last line typed, and positions 
the cursor at the end of the line, but does not 
o™ process the line. Press to process the 


line, or edit the line by backspacing. If you 
edit, press again to display the edited 


line. 
(CTRL ](D ) Redisplays the current command line. 
Temporarily halts video output. Press the 


space bar to resume output. 


ENTER Performs a carriage return or executes the 
current command line. 
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Sample Session 


Although BASICO9 has several functions or modes, they all work 
together to make programming as simple as possible. The easiest 
way to learn how BASICO9 and its functions operate is to write 
and run a program. This chapter provides sample statements 
and instructions to help you learn how to use BASICO9. 


To create and execute a program: 

1. Load BASICO9 and enter the edit mode. 
. Type the BASIC program. 
. Enter the system mode and test the program’s execution. | 
. Debug the program. (Correct any programming errors.) 


. Save the completed program on disk. 


Oo a Ff W Wb 


. Load the program into memory and use it. 


om To begin the program, execute BASICO9. To be sure you have 
enough room in which to work, reserve a workspace of 10,000 
bytes by typing: 


basic@9 #10K 


The BASICO9 system mode prompt, B:, appears after the copy- 
right message. In the system mode, you can do such things as 
save and load procedures, change workspace size, and rename 
and delete procedures. 


Creating a Procedure 


To write procedures, you must be in the edit mode. You get there 
by typing: 


e (ENTER) 


This causes the screen prompt to change to E:, and the screen 


on displays: 


PROCEDURE Program 


Because you didn’t give a program name when you entered e, 
BASICO9 selects the name Program for you. Now, you must | 
write the code to make Program do something. | 
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Commands and Program Lines 


There are two responses you can give at the edit mode prompt. 
You can type an edit command, or you can type a program line. 
If you type a program line, you must type a space as the first 
character in the line. If you type an edit command, do not pre- 
cede it with a space. To make listings easier to read, this man- 
ual uses the symbol [| to indicate spaces before every line. It also 
uses the |] symbol in some procedure lines to indicate the correct 
number of spaces needed. Whenever you see either a space or a [J 
symbol in a procedure you are typing, press the space bar. 


To type the procedure in this chapter, begin each line at the E: 
prompt. After typing a line, check it for mistakes. If you make a 
mistake, use to move the cursor back. Correct the mistake. 
Then, type the remaining portion of the line. If there are no mis- 


takes, press [ENTER ]}. 


BASICO9 checks each line when you press [ENTER]. If you make a 
mistake in syntax or form, BASICO9 displays an error message. 
An arrow points to the place in the program line where the error 
occurred, and a message number indicates the type of error. 
Refer to Appendix A for an explanation of the error codes. 


If, after you enter a line, you find that you made a mistake, type 
d to delete the line. Then, retype the line. Later, the man- 
ual tells you how to change text in existing lines. 


The following program helps you do a bit of arithmetic. To get a 
feel for BASICO9, type and execute the program as directed. 
Remember, when you see either a space or (|, press the space bar. 


ODIM NUMBER1 ,NUMBER2: INTEGER 

UINPUT “Type Number..."";NUMBER1 

UINPUT “Type another....™";NUMBER2 
OPRINT "The sum of the numbers is... "s 
UPRINT NUMBER1 + NUMBER2 

LEND 


ww 
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Executing a Procedure 


To execute the procedure, quit the edit mode by typing g (ENTER). 
The compiler further processes your procedure, and the B: 
prompt reappears. To execute the program, type: 


run | ENTER 


Type in numbers when asked, and the procedure produces their 
sum. If you want to save the program on disk, the next chapter 
tells you how. Chapter 4 introduces several other edit mode com- 
mands to search, display, insert, and change programs lines and 
text. 
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The System Mode 


The BASICO9 command interpreter processes system commands. 
At the B: prompt, you can enter system commands in either 
upper- or lowercase letters. Some commands operate on the pro- 
cedures in the workspace. Others provide functions independent 
of any procedures. Following is a list of all system commands 
and their purposes. 


Command 


$ 
BYE or 


CHD 


CHX 
or DIR 


EDIT or E 
KILL 


LIST 
LOAD 
MEM 
PACK 


RENAME 
RUN 


SAV E 


Function 


Calls the shell command interpreter to execute 


an OS-9 command. 


Returns you to the OS-9 system or to the pro- 
gram that called BASICOY. 


Changes the current OS-9 data directory. 
Changes the current OS-9 execution directory. 


Displays the name, size, and variable storage 
requirement of each procedure in the 
workspace. 


Enters the procedure editor-compiler mode. 


Erases one or more procedures from the work- 
space. 


Displays a formatted listing of one or more 
procedures. 


Loads all procedures from a disk file into the 
workspace. 


Displays in bytes the current workspace size, 
or reserves a specified amount of memory for 
the workspace. 


Condenses (compiles) one or more procedures. 
Changes a procedure’s name. 


Causes a procedure in the workspace to 
execute. 


Writes one or more procedures to disk. 
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Renaming Procedures 


BASIC09’s RENAME function is important for two reasons: 
First, it lets you load into the workspace procedures that have 
the same name. After you rename the workspace procedure you 
can load the second file. Second, if you let BASICO9 use the 
default procedure name, “Program,” you can rename the proce- 
dure before saving it to disk. By doing this, you avoid writing 
over—and destroying—an existing procedure file. 


To change the name of the procedure you created in the previous 
chapter from Program to Add, type: 


rename program add [ENTER 


Listing Procedure Names 


You can use the DIR command to see if RENAME worked prop- 
erly. DIR displays the names and sizes of all procedures in mem- 
ory. Because programmers use this command frequently, the 
system recognizes a shorthand call. Instead of typing dir [ENTER], 
you only need to press (ENTER). This displays a table of the proce- 
dures in the following format: 


Name Prec=Size Data-Size 

*add 182 32 

add1 217 42 

adde 218 42 
2198 free 


Proc-Size refers to the number of memory bytes required for the 
procedure. Data-Size refers to the number of memory bytes 
required for the procedure’s variables and data structures. The 
asterisk indicates the current procedure. System commands act 
on the current procedure unless you indicate otherwise. 


The last line of the DIR display tells you how many free bytes of 
memory remain in the BASICO9 workspace. 


Listing Procedures 


You can use the LIST command to view procedure lines. To dis- 
play the current procedure, type: 


list | ENTER 
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For example, this is the listing of a procedure named Alpha.bak: 


PROCEDURE Alpha__bak 


9000 DIM A:STRING 

9007 DIM TSINTEGER 

QOOBE 

QOOF PRINT “here iS the ‘alphedet 
backwards:" 

9032 PRINT 

9034 PUR: T=o8 TO -65. STEP <1 

004A PRINT CHRSCT): 

9051 PRL oe ees 

0057 NEXT T 

9062 PRINT 

9064 PRINT 

90966 END 


When you list a BASICO9 procedure, the system precedes each 
line with a relative storage address. The relative address of the 
first procedure line is always 0. In the previous example, the 
beginning address of the second procedure line in the workspace 
is 07 units from the beginning. The beginning address of the 
third line is OE hexadecimal (14 decimal) storage units from the 
procedure beginning. 


These I-Code addresses provide a way for the compiler to let you 
know where it finds an error when one occurs. 


Because BASICO9 compiles programs into I-Code, it must disas- 
semble them before it can display them on the screen. This 
means that the lines might not look exactly as typed. For 
instance, BASICO9 converts lowercase keywords (command 
names) to uppercase. BASICO9Y also eliminates some spaces. If 
your program uses control statements such as IF/THEN, FOR/ 
NEXT, and LOOP/ENDLOOP, the lines in these decision mak- 
ing or looping structures are indented as shown in the 
Alpha.bak example. Regardless of the appearance of your listed 
procedures, they execute correctly if you type their commands 
correctly. 
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Listing Procedures to a File 


There might be times when you want to send a formatted proce- 
dure listing, including I-Code addresses, directly to a file. You 
can do this using OS-9’s redirection symbol, >. To save the 
Alpha.bak procedure on a file named Alpha.list in the current 
data directory, type: 


Liat aipna.bar talpna. dist 


If you have several procedures in the workspace and want to list 
more than one to a disk file, separate the procedure names with 
commas, like this: 


list alpha.one,alpha.two,alpha.three >alpha.all 


In both of the preceding cases, the system creates the Alpha.list 
file and stores the specified listings in it. If you use a file name 
that already exists, BASICO9 displays the prompt: 


Rewrite?: 


If you press (Y], the system destroys the original file and over- 
writes it with the new listing. If you press (N), the LIST process 
terminates. 


If you wish to list a procedure, or group of procedures, to a file 
that is not in the current data directory, be sure to specify the 
complete pathlist, such as: 


list alpha.bak >» /d1/programs/alpha.rev [ENTER] 


Listing Procedures to a Printer 


In the same manner as you list procedures to a disk file, you can 
list one or more procedures to your printer. Make certain your 
printer is connected and turned on, then again use the redirec- 
tion symbol, but this time specify the printer device, like this: 


list alpha.bak »>/p [ENTER] 
Or: 
list alpha.one,alpha.two,alpha.three »>/p [ENTER] 
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Using a Wildcard 


Using the OS-9 wildcard, *, you can list all procedures in the 
workspace. For instance, if the procedures Alpha.one, Alpha.two, 
and Alpha.three exist, list them to the screen by typing: 


list* (ENTER] 

Send the list to a file by typing: 
list* alpha.all 

Or send the list to your printer by typing: 
list* /p 


Note: When you use the wildcard, the name of the file or 
device to receive the listing immediately follows the LIST” 
command. Do not use the redirection symbol. 


Saving Procedures 


You can save one or more procedures to disk using the SAVE 
command. Unlike LIST, SAVE does not include relative 
addresses. However, the syntaxes for the SAVE and LIST com- 
mands are identical. To save the procedure Alpha.bak to the cur- 
rent data directory, type: 


save alpha.bak alpha.bak 


If Alpha.bak is the current procedure, you can save it in a file 
named Alpha.bak by typing save [ENTER]. 


To save all of the procedures in the workspace to a file named 
All.programs in the current data directory, type: 


save* All.programs [ENTER 


As with LIST, to save one or more procedures in a file that is 
not in the current data directory, make sure you specify a com- 
plete pathlist. 


To save all the files in the workspace to a disk file with the 
same name as the current procedure, type save (ENTER ]. 


If the disk file you specify does not exist, BASICO9 creates it. If 
it does exist, the system displays the prompt: 


Rewrite?: 
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Press (Y) to write over the old file with the specified file. The old 
file is destroyed. 


Press (N] to terminate the SAVE operation. 


Loading Procedures 


To load a saved procedure back into BASIC09’s workspace, use 
the LOAD command and specify the appropriate pathlist. For 
instance, if your current directory is still the directory contain- 
ing Alpha.bak, load the procedure by typing: 


load alpha.bak 
To load Alpha.bak from the PROGRAMS directory on Drive /D1, 
type: 

load /d1/programs/alpha.rev 


You can run and edit a loaded procedure in exactly the same 
manner as you would a procedure you created. 


You can load any number of procedures into the workspace as 
long as your computer has sufficient memory. However, be care- 
ful that you do not load a procedure with the same name as a 
procedure already existing in the workspace. If you do, the new 
procedure overwrites (destroys) the original procedure. You can 
rename workspace procedures to avoid this problem. 


Deleting Procedures from the Workspace 


You can clear the workspace of one or more procedures using the 
KILL command. For instance, to remove Alpha.bak from the 
workspace, type: 


kill alpha.bak 


To remove more than one procedure from the workspace, sepa- 
rate the procedure names with commas. To delete Alpha.one and 
Alpha.two, type: 


kill alpha.one,alpha.two 


To clear the entire workspace, regardless of the number of proce- 
dures it contains, use the BASICO09 wildcard, *. Type: 


kill» (ENTER) 


| 


The System Mode / 3 


Changing Directories 


You change working directories in BASICO9 and OS-9 in the 
same manner, by using the CHD and CHX commands. CHD 
changes the data directory, and CHX changes the execution 
directory. 


BASICO9 saves files in, or loads files from, the data directory, 
unless you specify differently in the command pathlist. It stores 
packed procedures in, or loads PACKed procedures from, the exe- 
cution directory, unless you specify differently in the command’s 
pathlist. 


Also, if you want to access OS-9 commands from BASICO9, the 
system first looks for the commands in memory. If they are not 
there, it looks for them in the execution directory, unless you 
specify differently. 


If your data directory is the ROOT directory, and you wish to 
change to a directory named PROGRAMS that is a subdirectory 
of the ROOT directory, type the following command from the 
command mode B: prompt 


chd programs [ENTER 


If your current execution directory is the system’s CMDS direc- 
tory, and you want to change to a CMDS directory in the sub- 
directory BASIC, type: 


chx basic/cmds | ENTER 


Whenever you change to a directory other than an immediate 
subdirectory, specify a complete pathlist. 


Executing OS-9 Commands 


BASICO9 lets you use OS-9 commands at any time from the sys- 
tem mode. To do so, precede the command with a dollar sign ($). 
For instance, to look at the current data directory, type: 


$dir | ENTER 


To view the current execution directory, type: 


$dir x [ENTER] 
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All OS-9 commands are available, and you can copy files, format 
diskettes, list files, or use any other functions from the system 
mode. The only restriction is that your computer must have 
enough free memory to handle the command you call. If you find 
that there is not enough memory, try using the MEM command 
to reduce reserved memory. Then, try the command again. 


Auto-Execute Procedures 


The BASICO9 compiler makes two passes through the procedures 
you write. When you enter the command, the compiler performs 
an initial compilation, checking for any syntax errors. When you 
leave the edit mode, the system compiles the procedure a second 
time and checks for any programming errors. With the PACK 
command, you can further compile your procedures so that they 
are smaller and execute even faster. 


PACK causes an extra compiler pass that removes names, line 
numbers, and non-executable statements. Before packing a 
procedure, be sure you save it. Unless you do so, you can- 
not make further changes to the procedure. 


Once you pack a file, you cannot list or edit the packed version. 
However, if you save the procedure to disk before packing, you 
can still list and edit the original file, then pack it again. 


When you save a packed procedure on disk, BASICO9 does not 
normally store it in the data directory. Because the procedure is 
now executable, the system stores it in the current execution 
directory. 


For instance, to convert Alpha.bak to a packed procedure in the 
execution directory, type: 


pack alpha.bak 


If you want to save a packed procedure under a different file- 
name, use the OS-9 redirection symbol: 


pack alpha.bak > backwards [ENTER] 


After packing a procedure, you can delete it from the workspace. 
If you then run it, BASICO9 automatically loads the file from 
disk and executes it. 


The following is a sequence of commands that demonstrate pack- 
ing and executing a procedure named Alpha.bak: 
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pack alpha.bak packs the procedure and stores 
it in the execution directory. 


kill alpha.bak deletes the procedure from the 
workspace. 


run alpha.bak loads the file into memory 
outside the workspace and 
executes it. 


kill alpha.bak deletes the module from 
memory 


You do not need to kill the file immediately after execution, but 
until you do, the file reduces available memory. 
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The Edit Mode 


You briefly used the BASICO9 built-in editor to create the Add 
procedure in Chapter 2. In addition to the features you learned 
there, the editor has other important functions. 


Although you can use any text editor or word processor to write 
BASICO9 procedures, the BASICO9 editor offers two handy 
features: 


e It is both string and line number oriented. You can 
search for strings of characters, and replace them, and 
you can reference text with optional line numbers. 


® It interfaces with the compiler and decompiler. This fea- 
ture lets BASICO9 check continuously for syntax errors 
and enables you to use procedures that conserve memory. 


Edit Commands 


The following is a summary of the edit commands: 


Command Function 

Moves the edit pointer to the next line. Causes 
a command to execute. 

+ number Moves the edit pointer ahead number lines. 

+* Moves the edit pointer to the last line. 

-number Moves the edit pointer back number lines. 

-* Moves the edit pointer to the first line. 

text Inserts an unnumbered text line before the 


current line. 


ntext Inserts the line numbered n in its correct 
numeric position. 

n Moves the edit pointer to the line numbered n. 

c/str1/str2/ Changes the next occurrence of str1 to str2. 
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Command Function 

c*/str1/str2/ Changes all occurrences of str1 to str2. 

d Deletes the current line. 

d* Deletes all the lines in the procedure. 

] Lists the current procedure line. 

1* Lists all the procedure lines. 

q Terminates the edit session. 

r Renumbers lines beginning at the current line 
in increments of 10. 

yr” Renumbers all lines in increments of 10. 

rn Renumbers lines beginning at Line n in 
increments of 10. 

r ni n2 Renumbers lines beginning at Line ni in 
increments of n2. 

s /string/ Searches for the first occurrence of string. 

s* /string/ Searches for all occurrences of string. 


Using the Editor 


The easiest way to understand the edit commands is to use 
them. The following sections show you the functions of BASICO9 
edit mode. 


The manual uses line numbers in the following procedure to 
acquaint you with all the functions of the editor. Remember, 
however, line numbers are not required with BASICO9. Proce- 
dures and programs without line numbers are shorter, faster, 
and easier to read. 


First, you need a procedure with which to work. Position your- 
self in the system mode. Then, type this line: 


e prose (ENTER 
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Now, type the following. (Remember, the small rectangle repre- 
sents a space.) 


01080 DIM PHRASESC38):STRING 
120 FOR T=1 TO 30 

(1130 READ PHRASESCt) 

014@ NEXT T 

0160 PRINT 

0170 FIRST=RNDC10) 

018@ SECOND=RNDC9)+11 

L198 THIRD=RNDC9)+21 

298 PRINT PHRASESCFIRST); 
218 PRINT PHRASESCSECOND): 
Li22@ PRINT PHRASESCTHIRD); 
02408 PRINT 

308 DATA “"Lovell”,"An orangell™., 

“Humans Ty's" A kisali™ 

318 DATA "A dark cloudl","A goose featherL", 

"A Popsiclell” 

328 DATA "Home cookingl","Cold pizzal", 

“Roek nn” Roiilg" 

W338 DATA “is charming Likell”,“makes me dream ofl” 
348 DATA “is as sticky asl™,"can ooze 
likel","smells like" 

U3S8@ DATA “can be as Tough to forget. asl”, “can 
hurt like" 

368 DATA “can be as cynical asl","“makes a mockery 


off" 


0378 DATA “drives me as crazy as[l" 

Usee Dale “a Sticky -bollipopa™", "a Web oT 
intrigue.” 

398 DATA "castor oil.","a chocolate bath.","a 
broken toe." 

406 DATA “honey and things.",“personal 


déTeacts". a. Wel Crepers.” 
U41@ DATA “strange happenings.’ 
purses” 


; a- pPennyless 


When you finish typing the procedure, type q to return to 
the system mode. Now you can test the program by typing 
either: 


run | ENTER 


or 


run prose ENTER 


BASICO09 Reference 


After trying the procedure, return to the edit mode by typing e 
[ENTER J. 


After displaying the procedure’s name, the editor displays Line 
100 preceded by an asterisk. The asterisk lets you know which 
line is the current line (or the line at which the edit pointer is 
located). 


Searching Through a Procedure 

You can examine a procedure in three ways: 
@ Press to display the procedure one line at a time. 
@ Skip through the procedure to a particular line. 
e List part or all of the procedure to the screen. 


When you use either of the first two methods, the line you select 
to display becomes your current line. When you use the third 
method, the current line does not change. 


Using [ENTER 


If you are still positioned at Line 100, but want to examine the 
first line of data, Line 300, press 12 times to move down. 


Using the Plus Sign to Move Forward 


Another method of moving to a specific line is to type a plus 
sign followed by the number of lines you need to advance to get 
there. Positioned at Line 100, you can type: 


+12 | ENTER 


Whether you press or use the plus sign, the last line dis- 
played is now your current line. 
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Accessing a Line Using the Line Number 


The third way to move to a particular line is to type the line 
number, followed by (ENTER). For instance, to jump back to Line 
100, type: 

100 


The editor displays Line 100 and makes it your current line. 


Using the Minus Sign to Move Backward 


In the same manner that you move forward in the procedure 
using the plus sign, you can move backward using the minus 
sign, or hyphen. 


Type 30@ to return to Line 300. To display Line 240 and 
make it your current line, type: 


~ (ENTER) 


To display Line 190 and make it your current line, type: 


~ 4 (ENTER } 


The Global Symbol 


The BASICO9 editor also makes use of the asterisk as a global 
symbol. For instance, following a command with an asterisk 
causes that command to affect the entire procedure. 


This feature lets you move quickly to the beginning and end of 
the procedure. To return to Line 100, the first line, type: 


~* CENTER } 


To move to the end of the procedure, past all the numbered lines, 
type: 


+ * (ENTER) 
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Using LIST 


The LIST command lets you select one or more lines for display 
on your screen. To see this, make the first line your current line, 
then type: 


1 [ENTER ) 


To list one or more lines, type the LIST command followed by the 
number of lines you want displayed. For instance, typing 15 
causes the current line and four others to appear on the 
screen, as shown in the following sequence of commands and the 
resulting display: 


~ * CENTER] 


15 (ENTER } 
PROCEDURE Prose 


198 DIM PHRASESC3S8): STRING 
128. FUR T#1 10 32 

13@READ PHRASESCT) 

148 NEXT T 

160 PRINT 


You can also use LIST with the BASICO9 global symbol, *. Typ- 
ing an asterisk after the LIST command produces a listing of 
the entire procedure. 


Deleting Lines 


Earlier, the manual showed that you can delete the current line 
by typing d (ENTER). Because this is such a simple process, be 
sure you don’t do it by accident. Removing the wrong line, or too 
many lines, is very frustrating in a complex procedure. 


You can also remove a group of lines from a procedure by typing 
d, followed by the number of lines you want to delete. This com- 
mand deletes the current line and specified following lines. 
Again, be careful. 


You can remove all of the lines in a procedure by using the 
global symbol, *. Typing d* erases all procedure text. 
However, the procedure name still resides in the workspace. To 
delete an entire procedure, including the name, use the KILL 
command from the system mode. 
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If you decide you don’t like the nouns used in the DATA lines of 
the Prose procedure, erase all of the DATA lines containing 
nouns (Lines 300-320) and replace them. To do so, make Line 
300 your current line by typing: 


300 
Then type: 


d (ENTER) 


Line 300 disappears and Line 310 takes its place as the current 
line. 


An alternate method of deleting the DATA lines uses only one 
command. To delete Lines 300 through 410, follow the DELETE 
command with the number of lines you want to remove—in this 
case, three: 


d3 (ENTER) 


Lines 300, 310, and 320 disappear. Line 330 becomes the cur- 
rent line. Move back a line to check that the deletions worked. 
The line numbers now skip from 240 to 330. 


Now, you need new nouns for the procedure. Type them in the 
same style as the old lines, such as: 


308 DATA "A Telephonel],"A tickle", 

"A OLP Ah ah Boy 

0315 DATA “Bad luckO","Moneyl","A bad bet(", 
"A lumpy bed{" 

328 DATA “A deep thoughth";“Sunlighti” 


Save a copy of your procedure to disk by exiting the editor and 
using the SAVE command. Then return to the edit mode and try 
the global delete by typing: 


d* CENTER ] 


Changing Text 


Using CHANGE tells the editor to search for existing text and 
replace it with new text. CHANGE, like DELETE, can easily 
cause unwanted results if you are not careful. 
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The CHANGE command requires that you use delimiters to sep- 
arate the command from the search text, and to separate the 
search text from the new text. You can select any of the following 
characters for a delimiter, as long as it does not appear in either 
the search text or the new text: 


eee heds Sad a ee Se rE 


Do not use the global symbol (*) for search and replace opera- 
tions. This manual uses a slash (/) as the CHANGE delimiter. 


The following steps outline the correct use of CHANGE: 


1. Position the editor either before or on the line in which 
you want to make a change. 


2. Type c (for CHANGE). Do not use a preceding space. 
3. Type a delimiter character, such as /. 


4. Type the characters to be changed, following them with 
the delimiter. 


5. Type the new text, followed by the delimiter. 
6. Press (ENTER J. 


Note: It is a good idea to turn on OS-9’s upper- and lower- 
case function before attempting change or search opera- 
tions. If you do not, you cannot tell whether the text you 
want to find is upper- or lowercase, or some combination of 
the two. If you type the wrong case, the change or search 
fails. 


In case you didn’t notice when typing the procedure, Line 410 
contains an incorrectly spelled word, pennyless. To correct this 
error, type the following: 


c/pennyless/penniless/ 


Immediately, the editor displays Line 410, with pennyless 
changed to penniless. 


Suppose you decide to change the number of sentence combina- 
tions available in Prose. The procedure now has 30 data entries. 
If you add five subjects, five verb phrases, and five objects, the 
procedure also needs other changes (for instance, the DIM state- 
ment in Line 100, the loop size in Line 120, and the RND state- 
ments in Lines 170 through 190). 
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A quick way to change the number 30 in Lines 100 and 120 is 
to use CHANGE’s global function. To change all occurrences of 
30 to 45, position the editor at Line 100, and type: 


c*/30/45/ 


Use the CHANGE and global CHANGE functions to adjust the 
RND statement values in Lines 170, 180, and 190. 


As well as making changes, you can use the CHANGE command 
to quickly delete portions of text within a line. To do this, type 
delimiters without new text, in this fashion: 


c/feather// 


This command changes the text A goose feather in Line 210 
to A goose. 


Searching for Text 


The editor’s SEARCH command, S, works in the same manner 
as the CHANGE command. However, SEARCH only requires 
you to specify a block of text to find. 


With SEARCH, you use delimiters to enclose the text to find. To 
test the function, position the editor at the beginning of text by 


typing: 
se 

Now, search for the word phrases, by typing: 
s/phrases/ 

The screen displays: 
*9000 1080 DIM phrases€38):STRING 


To find all occurrences of phrases throughout the procedure, use 
the global symbol. Type: 


s*/phrases/ [ENTER 
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Renumbering Lines 


The RENUMBER command, R, reorders all numbered lines and 
all references to numbered lines. You can give RENUMBER 
either one or two parameters. The first is the beginning line 
number. The second is the increment you want. The default 
increment is 10. 


For instance, the Prose procedure line numbers skip from Line 
100 to Line 120. You can renumber the entire procedure by mov- 
ing the editor to Line 100, and then typing: 


r 10 ENTER 


To change the numbering to increments of 5, beginning at Line 
100, type: 


r 100,5 (ENTER ] 


You can also change line numbering in portions of the procedure. 
To do this move the editor to the line where you want the new 
numbering to begin. Then, type in the new parameters. To 
renumber Line 100 as Line 200 and continue with increments of 
10, position the editor at Line 100. Then, type: 


r 200,10 (ENTER) 


If you are not positioned at the first line of a procedure, but you 
wish to renumber all lines, you can use the global symbol to do 
the job. From anywhere in the procedure, type: 


r* 100,10 (ENTER) 


This renumbers the entire procedure in increments of 10. 


Adding Lines 
There are two ways to add new lines to a procedure. You can: 


e@ Position the editor one line below the position for the new 
line. Then, type the new line and press (ENTER). When 
inserting lines without numbers, be sure to type a space 
as the first character of the line to tell the editor that 
the following text is a new procedure line. 


e Type a new line, giving it a line number that falls 
between two existing line numbers. 


4-10 


The Edit Mode / 4 


The following procedure adds more choices to the Prose program. 
It also adds a feature that lets you press for additional 
output, rather than having to rerun the procedure. Use the 
information presented in this section to help you insert the new 
lines into your program. Because you must change some lines, 
as well as add lines, the following listing includes the entire 
procedure. 


Referring to the original Prose listing, the lines to change are: 
100, 120, 170, 180, and 190. 


The lines to add are: 110, 150, 230, 250, 260, 270, 305, 325, 
312,374, 076,-420, 430. 


PROCEDURE prose2 

1886 DIM PHRASESC45):STRING 

118 DIM RESPONSE:STRING 

120 FOR T=1 TO 45 

130 READ PHRASESCt) 

148 NEXT T 

158 REPEAT 

168 PRINT 

170 FIRST=RNDC15) 

188 SECOND=RNDC14)+16 

198 THIRD=RNDC14)+31 

200 PRINT PHRASESCFIRST); 

218 PRINT PHRASESCSECOND); 

220 PRINT PHRASESCTHIRD); 

230 PRINT 

240 PRINT 

25@ PRINT “CUOLOUDU00Press ENTER for another 
Wit tLerstivas. 

26@ INPUT “CUUILU0000Or press the SPACEBAR and press 
ENTER 10 @fidwas«"JRESPONSE 

279 UNTIL RESPONSES" 

300 DATA “Lovell™,"An orangel”,“Humanityl™, 
"A kiss(i" 

395 DATA “A computerQ","A bookO","Miseryl” 
318 DATA “A dark cloudi”,"A goose featnerl”, 
"A Popsiclel]” | 

328 DATA "Home cookingi","Cold pizzal", 
“Rock mn“ Roll” 

sea DATA “Snow in Junel","A glass house” 
338 DATA “is charming likel™,"makes me dream of" 
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340 DATA "is as sticky asf","can ooze likel", 
"smells likelL" 

3508 DATA "can be as tough to forget asl", 

“can hurt likel"™ 

3608 DATA "can be as cynical asl", 

“makes a mockery ofL" 

370 DATA "drives me as crazy asl" 

372 DATA “can bother me likel","blackens my hopes 
like" 

374 DATA "can tickle me likel","can be as funny 
as(]" 

376 DATA "has the effect ofl" 

380 DATA "a sticky lollypop.","a web of 
intrigue,” 

390 DATA "castor oil.","a chocolate bath.","a 
broken toe." 

400 DATA "honey and things.","personal 
defeat.","a wet diaper.” 

410 DATA "strange happenings.","a penniless 

Stir ses" 

420 DATA “a slimy snake.","a bad habit." 

430 DATA "a bad memory chip.","a good fight.","a 
Si lby triends” 


The Next Step 


Even the best programmers make mistakes—a lot of them. 
BASICO9 provides a way to catch programming mistakes quickly 
and correct them. The next chapter tells you about BASICO9’s 
powerful debugging functions. 
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The Debug Mode 


The term debug refers to the process of finding programming 
errors and correcting them. BASIC09’s debugging features 
include symbolic debugging capabilities that let you examine 
variable values and test and manipulate procedures. 


With Debug, you can: 
@ Examine and change variables. 


@ Trace procedure execution. Debug lets you execute proce- 
dures and watch them run in slow motion. 


® Pause procedure execution. 
@® Resume procedure execution. 


@ Set procedure breakpoints that automatically switch to 
the debug mode. 


® Select the use of degrees or radians for trigonometric 
functions. 


@ Perform calculations. 


® Call OS-9 system commands. 


Entering the Debug Mode 


You enter Debug: 


@ Automatically, whenever an error occurs during the exe- 
cution of a procedure (unless you have included an ON 
ERROR GOTO statement to handle the error). 


@ Automatically, when a procedure executes a PAUSE 


statement. 
@ When you press during the execution of a 
procedure. 


You can tell when BASICO9 enters the Debug mode by the 
appearance of the D: prompt. When you see D:, followed by the 
cursor, Debug is waiting for your command. 


The following is a reference of all the Debug commands and what 
they accomplish: 
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Command 


$ 


BREAK 


CONT 


DEG/RAD 
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Function 


Calls OS-9’s command shell interpreter to run 
a program or an OS-9 command. From the 
Debug prompt, type $, followed by the name of 
the program or command you want to execute. 


Example: $list procedure_—one (ENTER 


Sets a breakpoint immediately before the spec- 
ified procedure. Use this command to re-enter 
Debug when one procedure calls another. 


If you have three procedures that call each 
other—Procl, Proc2, and Proc3—and Proc3 
does not seem to pass the correct values to 
Proc2 when it returns, set a breakpoint at 
Proc2. This causes BASICO9 to enter Debug 
before re-entering Proc2. You can then check 
your variable values. 


You can use one breakpoint for each active pro- 
cedure. Debug removes breakpoints immedi- 
ately after encountering them. 


A procedure must run before you can set a 
breakpoint in it. Use BREAK to stop execution 
when a called procedure returns to a proce- 
dure previously executed. 


Example: BREAK proc2 


Causes procedure execution to continue. 


Example: cont (ENTER 


Selects either degrees or radians as the unit of 
measurement for trigonometric functions. DEG 
and RAD affect only the current procedure. 


Examples: deg (ENTER 
rad [ENTER 


DIR 


LET 


LIST 


PRINT 


STATE 
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Displays the name, size, and variable storage 
requirements of each procedure in the work- 
space. The current working procedure has an 
asterisk before its name. All packed proce- 
dures have a dash before their names. DIR 
also shows the available memory in the 
workspace. 


If you provide a pathlist, DIR sends its data to 
the specified file. 


Example: dir (ENTER 
dir procedures | ENTER 


Terminates execution of the procedure, closes 
any open paths, and exits to the System mode. 


Example: gq 


Assigns a new value to a variable. You must 
specify variable names that are already ini- 
tialized by your program. In the Debug mode, 
you cannot use LET to copy one array to 
another array as you can in BASIC 
procedures. 


Example: let a := @ (ENTER] 
let fruit := "oranges" (ENTER] 


Displays a source listing of the suspended pro- 
cedure. The display is formatted and includes 
I-code addresses. An asterisk appears to the 
left of the last executed statement. 


Example: list 


Displays the values of variables used in the 
suspended procedure. You cannot introduce 
new variable names in the Debug mode, and 
you cannot display array structures. 


Example: print fruit 


Lists the nesting order of active procedures. 
STATE displays the highest-level procedure at 
the bottom of the calling list. The lowest-level 
procedure is the suspended procedure. 


Example: state 
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STEP 


TRON/TROFF 


Causes execution of the suspended procedure 
in specified increments. For example, typing 
STEP S executes the equivalent of the 
next five statements. If you enter STEP with- 
out an increment value, the step rate is 1. 


Using STEP with the trace function lets you 
observe the source lines as they execute. 


Because compiled I-code contains actual state- 
ment memory addresses, the top or bottom 
statements of loop structures execute only 
once. For example, in FOR/NEXT loops, FOR 
executes once, and the statement following 
FOR appears to be the top of the loop. 


Turns on or turns off the trace function. Trace 
on (TRON) causes the system to reconstruct 
the compiled code of each statement line into 
source code. Debug displays the source code 
before the statement is executed. If the state- 
ment causes the evaluation of one or more 
expressions, Debug displays each result follow- 
ing the statement. The result is preceded by 
an equal sign. 


The trace function is local to the current pro- 
cedure. If the suspended procedure calls 
another procedure, Debug suspends the trace 
function until control returns to the original 
procedure. However, once you turn on trace for 
a procedure, it continues in effect until you 
turn it off. This means that if you turn trace 
on in a called procedure, and another proce- 
dure subsequently calls it, trace continues to 
display the called procedure’s operations. 


Example: tron (ENTER 
troff | ENTER 


When Things Go Wrong 


Programming errors show up in two ways. Either your procedure 
produces incorrect results, or it terminates prematurely. 
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In the first instance, you can stop your procedure and enter 


Debug by pressing (CTRL |(C}. 


However, sometimes your program executes too quickly to allow 
you to stop it at the appropriate place. In this case, you can use 
the Edit mode to insert a PAUSE command where you wish the 
procedure to stop. PAUSE causes the procedure to halt execution 
and enter the Debug mode. 


Once in Debug, you can use the PRINT command to examine 
the procedure variables. You can use LET to manipulate the 
variable values to determine where the error or errors occur. Per- 
haps you forgot to initialize a variable or forgot to increase a loop 
counter. 


Using the Trace Function 


Sometimes, errors are more difficult to discover. If so, the next 
step is to use the trace function. To do this, type: 


tron (ENTER | 


Now press (ENTER). Each time you press [ENTER], Debug executes 
one line of the procedure. You can see the original source state- 
ment, and if an expression is evaluated, Debug prints the result 
of the expression, preceded by an equal sign. 


In this manner, you can step through the entire procedure, or 
any part of it, examining variable values as you go. 


What About Loops? 


The STEP command is helpful if you find yourself tracing the 
operation of a loop. Once you determine that the loop works cor- 
rectly, you can avoid tedious, step-by-step repetitions by turning 
trace off and using STEP to quickly run through the loop. Then, 
turn trace back on and resume single-step debugging. For 
instance, type: 


troff (ENTER | 
step 200 
tron (ENTER | 
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In Multiple Procedures 


Although the trace function is local to a procedure, you can 
pause and turn on the trace function in as many procedures as 
you wish. Trace continues to operate in each procedure until you 
turn it off using TROFF. 


To cause a procedure to halt execution when it is called by 
another procedure, use the BREAK command. 
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Data and Variables 


Data Types 


Data is information on which a computer performs its operations. 
Data is always numeric but, depending on your computer appli- 
cation, it can represent values, symbols, or alphabetic characters. 
This means that the same items of physical data can have very 
different logical meanings, depending on how a program inter- 
prets it. 


For instance, 65 can represent: 
e A numeric value to be used in a calculation. 
@ The location of a memory address. 
@ The offset of a memory location. 
@ The two character symbols 6 and 5. 


@® The character A in the ASCII table. ASCII is the abbre- 
viation for the American Standard Code for Information 
Interchange. 


Because of the differences in how BASICO9 uses data, the sys- 
tem lets you define five types of data. For instance, there are 
three ways to represent numbers. Each has its own advantages 
and disadvantages. The decision to use one way or another 
depends on the specific program you are developing. The five 
BASICO9 data types are byte, integer, real, string, and Boolean. 


In addition to the preceding data types, there are complex data 
types you can define. The manual discusses complex data struc- 
tures at the end of this chapter. 


The byte, integer, and real data types represent numbers. 


The string data type represents character data (alphabet, punc- 
tuation, numeric characters, and other symbols). The default 
length of strings is 32 characters. Using the DIM statement, you 
can specify strings of both longer and shorter lengths. 


The Boolean data type represents the logical value, TRUE or 
FALSE. 
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You can create arrays (lists) of any of these data types with one, 
two, or three dimensions. The following table shows the data 
types and their characteristics: 


Memory 

Type Allowable Values Requirements 
BYTE Whole numbers (0 to 255) One byte 
INTEGER Whole numbers (-32768 Two bytes 

to 32767) 
REAL Floating point Five bytes 

( a 1*10 at 38) 
STRING Letters, digits, One byte per 

punctuation character 
BOOLEAN True or false One byte 


Real numbers appear to be the most versatile. They have the 
greatest range and are floating point. However, arithmetic opera- 
tions involving real numbers execute much more slowly than 
those involving integer or byte values. Real numbers also take 
up considerably more memory storage space than the other two 
numeric data types. 


Arithmetic involving byte values is not appreciably faster than 
arithmetic involving integers, but byte data conserves memory. 


If you do not specify the type of variable (a symbolic name 
for a value) in a DIM statement, BASIC09 assumes the vari- 
able is real. 


The Byte Data Type 


Byte variables hold unsigned eight-bit data (integers in the 
range 0 through 255). Using byte values in computations, 
BASICO9 converts the byte values to 16-bit integer values. If you 
store an integer value that is too large for the byte range, 
BASICO9 stores only the least-significant eight bits (a value of 
255 or less), and does not return an error. 
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The Integer Data Type 


Integer variables require two bytes (16 bits) of storage. They can 
fall in the range -32768 to 32767. If a calculation involves both 
integer values and real values, BASICO9 presents the result of 
the calculation as a real number. 


You can also use hexadecimal values in integer data. To do so, 
precede the value with the dollar sign ($). For instance, to repre- 
sent the decimal value 199 as hexadecimal, type $c7. The hexa- 
decimal value range is $0000 through $FFFF. 


If you give an integer variable a value that is outside the integer 
range (greater than 32767 or less than -32768), BASICO9 does 
not produce an error. Instead it wraps around the value range. 
For instance, the calculation 32767 + 1 produces a result of 
-32768. 


This means that numeric comparisons made on values in the 
range 32768 through 65535 deal with negative numbers. You 
should limit such comparisons to tests for equality or non- 
equality. Functions such as LAND, LNOT, LOR, and LXOR use 
integer values but produce results on a non-numeric, bit-by-bit, 
basis. 


Division of an integer by another integer yields an integer. 
BASIC09 discards any remainder. 


The Real Data Type 


If you do not assign a data type to a variable, BASICO9 assumes 
the variable is real. However, programs are easier to understand 
if you define all variable types. 


BASICO9 stores as real values any constants that have decimal 
points. If a constant does not have a decimal point, BASICO9 
stores it as an integer. 


BASICO9 requires five consecutive memory bytes to store real 
numbers. The first byte is the exponent, in binary two’s comple- 
ment. The next four bytes are the binary sign and magnitude of 
the mantissa. The mantissa is in the first 31 bits; the sign of 
the mantissa is in the last (least-significant) bit of the last byte. 
The following illustration shows the memory storage of a real 
number: 
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Internal Representation of Real Numbers 


exponent mantissa 


byte: 0 f! 2 3 4 


The exponent covers the range 2.938735877x10~ °° (2-128) 
through 1.701411835x10** (2!2) as powers of 2. Operations that 
result in values out of the representation range cause an over- 


flow or underflow error. You can handle such errors using the ON 
ERROR command. 


The mantissa covers the range 0.5 through .9999999995 in steps 
of 2~-*1. This means that real numbers can represent values 
.0000000005 apart. BASICO9 rounds operation values that fall 
between these points to the nearest point. 


Because floating point arithmetic is inherently inexact, a 
sequence of operations can produce a cumulative error. Proper 
rounding, as implemented in BASICO9, reduces the effect of this 
problem, but cannot eliminate it. When using real quantities in 
comparisons, be sure your computations can produce the exact 
value you desire. 


String Variables 


A string is a variable-length sequence of ASCII values. The 
length can vary from 0, a null string, to the capacity of the 
memory available to BASICOY. 


You can define a string variable either explicitly, using the DIM 
statement, or implicitly by appending the dollar sign ($) to the 
variable identifier (variable name). For example, title$ implicitly 
identifies a string variable. 


Unless you specify otherwise, BASICO9 assigns a maximum 
string length of 32 characters. Using the DIM statement, you 
can specify a maximum length either less than or greater than 
32. To conserve memory, use DIM to assign only the maximum 
length you need for any string variable. 


The beginning of a string is always Character 1. The BASE 
statement, which sets numeric variable base numbers as either 0 
or 1, does not affect string variables. 
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If an operation results in a string too long to fit in the assigned 
maximum storage space, the system truncates the string on the 
right. It does not produce an error. 


String storage is fixed at the dimensioned length. The sequence 
of actual string byte values is terminated by the value of zero, or 
by the maximum length allotted to the string. Any unused stor- 
age after the zero byte allows the stored string to expand and 
contract within its assigned length. 


The following example shows the internal storage of a variable 
dimensioned as string [61] and assigned the value “SAM”. 
Note that Byte 4 contains the string terminator 00. The string 
does not use bytes following 00. 


stat mu{ol | 
byte: if 2 3 4 5 6 


If you assign the value “ROBERT” to the variable, BASICO9 does 
not need to terminate the string with 00 because the string is 


full: 
LR Blel{rR{t. 
byte: i Z 3 4 5 6 


The way BASICO9 handles string storage is important when you 
write programs. If you do not specify a length for strings you 
define, the system uses the default length 32. As you can see, 
this wastes computer memory if you store strings of only four or 
five characters. 


The Boolean Type 


A Boolean operation always returns either the character string 
“TRUE” or “FALSE”. You cannot use the Boolean data type for 
numeric computation—only for comparison logic. 


Do not confuse the Boolean operations AND, OR, XOR, and NOT 
(which operate on the Boolean values TRUE and FALSE) with 
the logical functions LAND, LOR, LXOR, and LNOT (which use 
integer values to produce numeric results on a bit-by-bit basis). 
An attempt to store a non-Boolean value in a Boolean variable, 
causes an error. 
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Automatic Type Conversion 


When an operation mixes numeric data types (byte, integer, or 
real values), BASICO9 automatically and temporarily converts 
the values to the type necessary to retain accuracy. This conver- 
sion lets you use numeric quantities of mixed types in most 
calculations. 


The system returns a type-mismatch error when an expression 
includes types that cannot legally mix. These errors are reported 
by the second compiler pass, which occurs automatically when 
you exit the edit mode. 


Because type conversion takes additional execution time, you can 
speed calculations by using values of a single type. 


Constants 


Constants are values in a program that do not change. They can 
use any of the five data types. The following are examples of con- 
stants in a procedure: 


HOME$=""Fort Worth" 
VALUE$=""$25 , 008 
VALUE#=25 

PAYMENT #99.99 
ANSWER=""TRUE" 
MEMORY=$@CFF 

PRINT “tne ina” 


Numeric constants are either integers or real numbers. If a 
numeric constant includes a decimal point or uses the “E format” 
exponential form, it causes BASICO9 to store the number in the 
real format, even if it could store the number in integer or byte 
format. 


You can use this feature to force a real format. For instance, to 
make the number 12 a real number, type it as 12.0. You might 
want to force real values in this way when all other values in an 
expression are real so that BASICO9 does not have to do a time- 
consuming type conversion at run time. 
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BASICO9 also stores as real numbers any numbers that do not 
have decimal points but that are too large to store as integers. 
Here are some examples of legal real constants: 


1.0 9.8433218 -.O1 
-999.000099 100000000 0644.34532 
1.95E +12 -99999.9E-33 


BASICO9 treats numbers that do not have a decimal point and 
are in the range -32768 through +32767 as integers. You must 
always precede hexadecimal numbers with a dollar sign. 


Following are examples of legal integer constants: 


12 -3000 D5 
$20 $SFF $09 
0 -12 -32768 


String Constants 


A string constant consists of a sequence of characters enclosed in 
double quotation marks, such as: 


“The End™ 


To place a string constant in a string type variable, use the 
equal symbol in this manner: 


TITLES = "Masters Of Magic" 


To include double quotation marks within a string, use two sets 
of double quotation marks, like this: 


"An ""older man" is wiser." 


A string can contain characters that have ASCII values in the 
range 0 through 255. 


Variables 


In BASICO9, a variable is local to the procedure in which it is 
defined. A variable defined in one procedure has no meaning in 
another procedure unless you use the RUN and PARAM state- 
ments to pass the variable when you call the other procedure. 


The local nature of variables lets you use the same variable 
name in more than one procedure and, unless you specify other- 
wise, have the variables operate independently of each other. 
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You can assign variables using either the LET statement with 
the assign symbol (=), or by using the assign symbol alone. For 
instance, both the following command lines are legal: 


LET PAYMENT#=44.58 
PAYMENT =44.58 


When you call a procedure, BASICO9 allocates storage for the 
procedure’s variables. It is not possible to force a variable to 
occupy an absolute address in memory. When you exit a proce- 
dure, the system returns the storage allotted for variables, and 
you lose the stored values. 


If you write a procedure to call itself (a recursive procedure), the 
call creates separate storage space for variables. 


Note: Unlike other BASICS, BASICO9 does not automati- 
cally initialize variables by setting them to zero. When you 
execute a procedure, all variables, arrays, and structures 
have random values. Your procedure must initialize the 
variables you specify to the values you require. 


Passing Variables 


When one procedure passes variable values to another procedure, 
BASICO9 refers to the passed variables as parameters. You can 
pass variables either by reference or by value. 


BASICO9 does not protect variables passed by reference. There- 
fore, the called procedure can change the values and return the 
new values. BASICO9 does protect variables passed by value, so, 
the called program cannot change them. 


To pass a parameter by reference, enclose the name of the vari- 
able in parentheses as part of the RUN statement in this 
manner: 


RUN RANDOMC16) passes the value 10 to a procedure 
called Random 


The system evaluates the storage address of each passed vari- 
able, and sends the variable to the called procedure. The called 
procedure associates the storage addresses with the names in its 
local PARAM statement. It then uses the storage area as though 
it had created it locally. This means it can change the value of 
the parameter before returning it to the calling procedure. 
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To pass parameters by value, write the value to be passed as an 
expression. BASICO9 evaluates the expression at the time of the 
call. To use a variable in an expression without changing its 
value, use null constants, such as 0 for a number or "" for a 
string, in this manner: 


RUN ADDCOLUMNCx+9) passes the value of x by 
value 

RUN TRANSLATECwS$+"""") passes the contents of w$ by 
value 


To pass parameters by value, BASICO9 creates a temporary vari- 
able. It places the result of the expression in the temporary vari- 
able and sends the address to the called procedure. This means 
that the value given to the called procedure is a copy of the 
result of the expression, and the called procedure cannot change 
the original value. 


The results of expressions containing numeric constants are 
either integer or real values; there are no byte constants. To 
send byte-type variables to a procedure, pass the values by refer- 
ence. Therefore, if a RUN statement evaluates an integer as a 
parameter and sends it to a byte-type variable, the byte variable 
uses only the high-order byte of the two-byte integer. 


Arrays 


An array is a group of related data values stored consecutively 
in memory. The system knows the entire group by a variable 
name. Each data value is an element. You use a subscript to refer 
to any element of the array. For example, an array named Graf 
might contain five elements referred to as: 


GRAF C1) GRAF C2) GRAF C3) GRAF C4) GRAF C5) 


You can use each of these elements to store a different value, 
such as: 


GRAFC1) = 25 
GRAFC2) = 47 
ORAF CS) = 39 
GRAF C4) = 16 
GRAFCS) = 58 
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Note: Normally, array elements start with 1 in BASICO9. 
However, you can use the BASE command to cause array 
elements to begin at 0. 


The previous example illustrates a single-dimensioned array. The 
elements are arranged in one row and only one subscript is used 
for each element. 


The following procedure lets you type values for a GRAF array, 
and displays the results in a simple graph. 


PROCEDURE GRAF 

UDIM GRAFC5):REAL 

(SHELL “DISPLAY @c"™ 

FOR T=1 TO 5S 

UPRINST “Value for tem #"% Ts “is 
INPUT GRAF Ct) 

LINEXT T 

PRINT 

LIPRINT 

PRINT “This is how your graph. stacks up...” 
LIPRINT 

UPOR T=7+ Ta §& 

UPRIANT “Diem #™s Ts “is 

LIFOR U=1 TO GRAFCT) 

PRINT CHRSC€79): 

UNEXT U 

LIPRINT 

AD, te, ae 

UPRINT 

HEND 


This program uses a single dimension array—in effect, a list. 


You can also create arrays with more than one dimension — 
more than one element for each row. You might use a two-dimen- 
sioned array in a program to store names and addresses. Instead 
of creating separate arrays for the name, address, and zip code, 
you could set up one array with two dimensions. 
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The following program, used to enter the names of a company’s 
employees, shows how this might be done. See the second line for 
the DIM syntax. When you run the procedure, it asks you for a 
name, address, and zip code for each of 10 employees. After you 
type the information for all the entries, the procedure displays 
the information on the screen. 


PROCEDURE Names 

UDIM NAMEC1@,3):STRING 

SHELL. -“DISPEAY 8c" 

LIBASE @ 

UFOR T=@ TO 9 

LIPRINT “Type Employes Name Now"; Ty "es * 5 
UINPUT NAMECT,@) 

UIPSINT “Type Employee Address No. "s Ty "ae 7 
LDINPUT NAMECT,1) 

UPRINT “Type Employee Zip Code Now's Ts s 
INPUT NAMECT.,2) 

UNEXT T 

SHELL: “DISPLAY @C™ 

OPRINT “And the names are..." 

LIPRINT 

LIFOR T=@ TO 9 

HRRIST NAMECT, O22 “Us NAMECE st 3s" -NAMECT «223 
UNE) 

LIEND 


The DIM statement reserves space in memory for a string array 
named Name, with two dimensions. As you enter data, the Name 
field is stored in Name(@,0), Name(1,0), Name(€2,0), and so on. 
The Address field is stored in Name(€@,1), Name(1,1), 
Name(2,1), and so on. The Zip field is stored in Name(@,2), 
Name(1,2), Name€2,2), and so on. This continues until you fill 
the grid, 10 entries with three items each. 


You can also create arrays with three dimensions. The following 
program adds one more dimension that keeps track of each 
employee’s company. It dimensions Name$ as Name$(2,10,3). 
The first dimension contains either 0 or 1 to indicate to which 
company the employee belongs. 
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PROCEDURE names2 


UDIM NAME$C€2,18,3):STRING 
SHELL "DISPLAY ec” 

UBASE @ 

UFOR X=@ TO 1 

UPRINT 

LIPRINT 

UFOR T=8 TO 9 

UPRINT 


IF X=@ THEN 
UPRINT "Type a Wiggleworth Company employee 
name..." 


hs og 3 


UJENDIF 

PRINT “Tyne: Name Nee > 14.7% <3 
HINPUT NAME$CX,T,0) 

UPRINT “Tyee. Address New™s Te. sO 
OINPUT NAME$CX,T,1) 

PRIM. “Tyee 2ip Code Now's: 14° 04.93 
DINPUT NAME$CX,T,2) 

ONEXT T 

OINEXT xX 

MSHELL. “DISPLAY #@Cc”™ 

OPRINT "The Wiggleworth employees are..." 
LUPRINT 


a | 


Ux=0@ 

UFOR T=@ TO 9 

DPRINT NAMESCX,7T,8)s “Os NAMESCX,T,193 “U"s 
NAME$CX,T,2) 

UNEXT T 

UPRINT 


— 


OPRINT “The Putforth Company employees are...” 
UPRINT 

LIX = 1 

FOR T=2@ 70 2 

OPRINT NAMES$CX,T,9); “UO; NAMESCX,T,193; “O's; 
NAME$CX,T,2) 

BNEXT Tf 


END 
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The easiest way to understand three dimensional arrays is to 
consider the first dimension as a page. In other words, if the first 
dimension in the string is 0, the employee is on the Wiggleworth 
Company’s page. If the first dimension in the string is 1, the 
employee is on the Putforth Company’s page. 


Complex Data Types 


In addition to the five standard data types, you can create your 
own data types. Using the TYPE command, you can define a 
new data type as a vector (a single-dimensioned array) of any 
previously defined type. 


For example, in the previous program, the Name variable can 
contain only one type of data, the string type. However, using 
the TYPE command you can create a variable that accepts sev- 
eral data types. 


Suppose you create an employee list procedure that uses the fol- 
lowing variables, of the following size and types: 


Name Length Contents Type 
Name 25 employee name string 
Street 20 street address string 
City 10 city of address string 
Zip — address zip code integer 
Sex — false = male, true = female Boolean 
Age — employee age byte 


You can combine all these variables into one complex data type. 
To do so, dimension the variables within a TYPE command line, 
like this: 


TYPE EMPEDYEE=NAMESSI RING 2S)]¢ SIREETESPR ING LEY I 5 
CLIYSSIRINGIIOI2 Z2ZIPSREALS SEATBORVLEAR? AGESEYTE 


This creates a new BASICO9 type, called Employee. Employee 
requires its variables to have six fields of the name, size, and 
type shown in the previous chart. 


Once you create the new data type, you can define variables to 
use it. For instance, the following program line defines Worker as 
type employee, with 10 elements in the array: 


UDIM WORKERC10):EMPLOYEE 
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To put the employee data type to work, collect your data with 
INPUT commands. Then, store the data into the new Worker 
array. The following program demonstrates how you might do 


this: 


PROCEDURE worker 
UREM 


Dimension variables for 


input 


UDIM 
UDIM 
UDIM 
UDIM 
UDIM 
UDIM 
UREM 


type 


NMS STRINGL 25 1 
SIs STRINGC2O) 
CTY:STRING((9@) 
ZPsREAL 
SX:BOQLEAN 
AG: BYTE 
Create new type and array using new 


UTYPE EMPLOYEE=NAME:STRING[25]; 
CITYEStRINGLITS J ZEPSREALS 
UDIM WORKERC1@):EMPLOYEE 


SEX: BOOLEAN; 


DIREETTSTRINGL eC 13 
AGE: BYTE 


UREM 

UFOR T= 
LLENPUT 
UINPUT 
UINPUT 


1 TO 10 
"“Name:l"',NM 
“Street <i", ST 
MOLEC ely 


INPUT 
LDINPUT 
UDINPUT 
UREM 
field names 
UWORKERCT).NAME=NM 
OWORKERCT).STREET=ST 
UWORKERCTI.CITY=CTY 
UWORKERCT).ZIP=ZP 
UWORKERCT).SEX=SX 


UWORKERCT).AGE=AG 


TEES per 
“Sex ei". Sox 
"Ages", AG 

store input 


UPRINT WORKERCT).NAME 
UPRINT WORKERCT).STREET 
UPRINT WORKERCT).CITY 
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LIPRINT 

UNEXT T 

ISHELL “DISPLAY €o0Co" 

PRINT “Fhe Vanes 29 your Files 1e@. ares. 
PRINT 

Per T=1 Th TO 


in the Worker array using 


Ww 
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UPRINT WORKERCT).ZIP 
DIF WORKERCT).SEX=TRUE 
OTHEN PRINT "Female" 


ELSE 

UPRINT "Male" 

UENDIF 

UPRINT WORKERCT).AGE 
UPRINT 


OPRINT "* * * * * © * & & & & & % & &# & & & & NM 
UPRINT 
(NEXT | 


Note that the Sex field is defined as Boolean. This means that 
you can respond only in two ways, TRUE or FALSE. The method 
of input requires only one byte of storage. To use this data you 
need to handle it so TRUE and FALSE indicate female and male. 


Complex data types can contain more than one field. Each field 
can be of any data type. You reference the fields of a complex 
data type by typing the variable name, its array index, a period 
(.), and the field name. The following lines, from the Worker pro- 
cedure, show how BASICO9 stores the data from the input lines 
into the Worker variable: 


WORKERCT).NAME=NM 
WORKERCT).STREET=ST 
WORKERCT).CITY=CTY 
WORKERCT).ZIP=ZP 
WORKERCT).SEX=SX 
WORKERCT).AGE=AG 


These lines store the values in the variables NM, ST, CTY, ZP, 
SX, and AG into the NAME, STREET, CITY, ZIP, SEX, and 
AGE fields of the Worker variable. This operation is within a 
FOR/NEXT loop that uses T as a counter. In the procedure, T 
can refer to a value in the range 1 to 10. 


The procedure uses the same type of operation to extract the 
data from the complex data type variable: 
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PRINT WORKERCT).NAME 

PRINT WORKERCT).STREET 

PRINT WORKERCT).CITY 

PRINT WORKERCT).2ZIP 

[IF WORKERCT2.5EX=TRUE. THEN PRINT “Female” 
ELSE PRINT “Male 

ENDIF 

PRINT WORKERCT).AGE 


Using the same methods, you can create complex data types that 
combine other complex data types and standard data types. 


The elements of a complex structure can be copied to another 
similar structure. Using a single assignment operator, you can 
write an entire structure to, or read an entire structure from, 
mass storage as a single entity. For example: 


PUT #2, WORKERCT) 


Because the system defines the elements of complex-type storage 
during compilation, it need not do so during runtime. This 
means that BASICO9 can reference complex structure faster than 
it can reference arrays. 
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Expressions, Operators, and 
Functions 


Manipulating Data 


BASICO9 uses expressions to manipulate data. (Expressions are 
pieces of data connected by operators.) 


An operator is a symbol or a word that signifies some action to 
be performed on the specified data. Each data item is a value. 


Expressions 


When an expression is evaluated, the result is a value of some 
data type (real, integer, string, byte, or Boolean). 


An expression might look like this: 


First First Second Second 
cry Value Operator Value Operator’ Result 
6 + 5 = al 


or like this: 


First First Second Second 
Value Operator Value Operator Result 


“Seaside” “Villa” Seaside 
Villa 


When BASICO9 evaluates an expression, it copies each value onto 
an expression stack. Functions and operators take their input 
values from this stack and return their results to it. Many 
expressions result in assignments, as do the examples shown. 
The BASICO9 makes the resulting assignment only after it com- 
putes the entire expression. This lets you use the variable that is 
being modified as one of the values in the expression, such as in 


© | this example: 
X=X+1 
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The result of an expression is always one of the five BASICO9 
data types. However, you can often mix data types within an 
expression and, in some cases, the result of an expression is of a 
different data type than any of the values in the expression. 
Such is the case if you use the less-than symbol (<), in this 
manner: 


24 < 108 


The less-than operator compares two integer values. The result 
of the comparison is Boolean; in this case, the value is TRUE. 


Type Conversion 


Because BASICO9 performs automatic type conversion of values, 
you can mix any of the three numeric data types in an expres- 
sion. When you mix numeric data types, the result is always of 
the same type as the value having the largest representation, in 
this order: real < integer < byte. 


You can use any numeric type in an expression that produces a 
real number. If you want an expression to produce a byte or inte- 
ger type value, the result must be small enough to fit the 
desired type. 


Operators 


BASICO9 has operators to deal with all types of data. Each oper- 
ator, except NOT and negation (unary -), takes two values or 
operands, and performs an operation to produce a result. NOT 
can accept only one value. The following table lists the operators 
available and the types of data they accept and produce. 


Because the same operators function on the three types of 
numeric data (byte, integer, and real), these types are referred to 
by the operand type “numeric.” 
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BASIC09 Expression Operators 


Operator 


“or ** 


“x 
/ 


<> or >< 


< 


<= or =< 


> 


Operand Result 

Function Type Type 
Negation numeric numeric 
Exponentiation numeric numeric 
Multiplication numeric numeric 
Division numeric numeric 
Addition numeric numeric 
Subtraction numeric numeric 
Logical Negation Boolean Boolean 
Logical AND Boolean Boolean 
Logical OR Boolean Boolean 
Logical Exclusive OR Boolean Boolean 

Concatenation string string 
Equal to all types Boolean 
Not equal to all types Boolean 
Less than numeric, stringt Boolean 


numeric, stringt Boolean 
numeric, stringt Boolean 


Less than or equal 
Greater than 


= or => Greater than or equal numeric, stringt Boolean 


+ When comparing strings, BASICO9 uses the ASCII values of 
characters as the basis for comparison. Therefore, 0 < 1,9 < A, 
A < B, A < b, b < z, and so on. 


Arithmetic Operators 


Arithmetic operators perform operations on numeric data. There- 
fore, both operands in the expression must be numeric. The fol- 
lowing table lists the arithmetic operators. 


Negation The single dash negates a number’s sign: 
-10 is negative 10. 

Exponentiation Use a caret (*) or two asterisks (**) to raise 
a number to a power: 23 is 8 (2 x 2 x 2). 
Similarly, 2**3 is 8. 

Multiplication A single asterisk causes multiplication: 
2*3 is 6. 

Division A slash causes division: 6 / 2 is 3. 
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Addition The plus sign causes addition: 3 + 3 is 6. 


Subtraction A dash causes subtraction: 6 - 3 is 2. 


Hierarchy of Operators 


BASICO9 uses the standard hierarchy of operations when calcu- 
lating expressions with multiple operators. This means that 
BASICO9 has an order in which it performs calculations involv- 
ing more than one operator. 


The following BASICO9 operators are listed in order of 
precedence: 


NOT  -— (negate) 
“ *KK 


3 / 

- ss 

— a — ae a 
AND 

OR XOR 


Also, BASICO9: 


e Performs operations enclosed in parentheses before oper- 
ations not in parentheses. 


e Performs the leftmost operations first when two or more 
operations are of equal precedence. 


You can use parentheses to override this standard precedence. 
For example: 


but 
C2. > > eS 2 


The following examples show BASICO9 expressions on the left, 
and the way BASICO9 evaluates them on the right. You can 
enter the expressions in either form, but the decompiler gener- 
ates the simpler form, shown on the left. 
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BASIC09 Equivalent 
Representation Form 
Cy a=b+cx**2/d a=b+ ((c**2)/d) 
a=b>c AND d>e OR a=((b>c) AND (d>e)) 
c=e OR (c=e) 
a=(b+c+d)/e a=((b+c)+d)/e 
a=bx«cx*d/e | a = (b**(c**d))/e 
a= -(b)**2 a = (-b)**2 
a=b=c a=(b=c) 


Relational Operators 


Relational operators make logical comparisons of any type of data 

and return a result of either TRUE or FALSE. An explanation of 

the relational operators follows. All relational operators have 
a equal precedence. 


=: Equal. Returns TRUE if both operands are 
equal, or FALSE if they are not equal. 


< Less than: Returns TRUE if the first operand is 
less than the second, or FALSE if is not. 
> Greater than: Returns TRUE if the first operand 


is greater than the second, or FALSE if it is not. 


<> or >< Unequal: Returns TRUE if the operands are not 
equal or FALSE if they are. 


<= or =< Less than or equal to: Returns TRUE if the first 
operand is less than or equal to the second 
operand. Otherwise, the operation returns 
FALSE. 


>= or => _— Greater than or equal to: Returns TRUE if the 
first operand is greater than or equal to the 
-_ second. Otherwise, the operation returns FALSE. 
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You normally use relational operators in IF/THEN statements. 
For example, if your procedure has two numeric variables, Pay- 
ments and Income, you might include command lines like this: 


IF PAYMENTS >» INCOME THEN 
PRINT "You’re Broke!" 
ENDIF 


When you combine arithmetic and relational operators in the 
same expression, BASICO9 evaluates the arithmetic operations 
first. For example: 


IF X*Y/2 <= 14 THEN 
PRINT “Average score 19 °°%. A*7¢2 
ENDIF 


BASICO9 performs the arithmetic operation x*y/2, then compares 
the result with the value 14. 


When you use relational operators with strings, BASICO9 com- 
pares the strings character by character. When it finds two char- 
acters that do not match, it checks to see which character has 
the lower ASCII code value. The string containing the character 
with the lower value comes first. 


Consider this example: 
PRINT Shunt’ 2° ""hune” 


BASICO9 compares each character in each string. Because the 
first three characters are the same, the result of the operation is 
based on the comparison of t and g. Because t (ASCII value = 
116) is “greater than” g (ASCII value = 103), the command 
prints TRUE. 


String Operators 


The string operator is the plus sign (+). This symbol appends 
one string to another. All operands must be strings, and the 
resulting value is one string. Examine, for example, the follow- 
ing line, which appends three strings: 


PRIA “ty Tr hends are "+ "Jeet and " #°"vilten 


It prints: My friends are Jack and Jill. 
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Logical Operators 


The logical, or Boolean, operators make logical comparisons of 
Boolean values. The following table describes the results yielded 
by each logical operator given the specified TRUE/FALSE values: 


Meaning of First Second 
Operator Operation Operand Operand' Result 
NOT The result is the opposite of TRUE FALSE 
the operand. FALSE TRUE 
AND When both values are TRUE, TRUE TRUE TRUE 
the result is TRUE. TRUE FALSE FALSE 
Otherwise, the result is FALSE TRUE FALSE 
FALSE. FALSE FALSE FALSE 
OR When both values are TRUE TRUE TRUE 


FALSE, the result is FALSE. TRUE FALSE TRUE 
Otherwise, the result is FALSE TRUE TRUE 


TRUE. FALSE FALSE FALSE 
XOR When only one of the values TRUE TRUE FALSE 
is TRUE, the result is TRUE FALSE TRUE 
TRUE. Otherwise the result FALSE TRUE TRUE 
is FALSE. FALSE FALSE FALSE 


Use logical operators in IF/THEN statements such as: 


IF PAYMENTS < INCOME AND INCOME+SAVINGS »> 
PAYMENTS THEN 

PRINT "You’ll have to use your savings to get 
out of this mess." 
ENDIF 


Functions 


Functions are operation sequences the system performs on data. 
In a statement, BASICO9 performs functions first. Chapter 11, 
“Command Reference,” describes the following functions. 
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Functions returning results of type real 


SIN 

COS 
TAN 
ASN 
ACS 
ATN 


LOG 


LOG10 
EXP 


FLOAT 


INT 


PI 
SQR 
SQRT 


RND 


Calculates the trigonometric sine of a number. 
Calculates the trigonometric cosine of a number. 
Calculates the trigonometric tangent of a number. 
Calculates the trigonometric arcsine of a number. 
Calculates the trigonometric arccosine of a number. 


Calculates the trigonometric arctangent of a 
number. 


Calculates the natural logarithm (base e) of a 
number. 


Calculates the logarithm (base 10) of a number. 


Calculates e (2.71828183) raised to the specified 
positive power. 


Converts byte or integer type numbers to real 
numbers. 


Calculates the largest whole number less than or 
equal to the specified number. 


Represents the constant 3.14159265. 
Calculates the square root of a positive number. 


Calculates the square root of a positive number. Its 
function is identical to SQR. 


Returns a random number. 
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Functions returning results of any numeric type 


The resulting type depends on the input type. 


ABS 
SGN 


SQ 
VAL 


Calculates the absolute value of a number. 


Returns a value to indicate the sign of the specified 
number (-1 if the number is less than 0, 0 if the 
number is 0, or 1 if the number is greater than 0). 


Calculates the square of a number. 


Converts a string to a numeric value. 


Functions returning results of type integer or type byte 


FIX 


MOD 


ADDR 


SIZE 


ERR 
PEEK 


POS 


ASC 


LEN 
SUBSTR 


Rounds a real number and converts it to an 
integer. 


Calculates the modulus (remainder) of two 
numbers. 


Returns the absolute memory address of a 
variable, an array, or a structure. 


Returns (in bytes) the storage size of a variable, 
an array, or a structure. 


Returns the error code of the most recent error. 


Returns the byte value at a specified memory 
address. 


Returns the current character position of the 
print buffer. 


Returns the numeric value (ASCII code) of a 
string character. 


Returns the length of a string. 


Returns the starting position of the specified 
substring within a string, or returns 0 if it 
cannot find the substring. 
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Functions performing bit-by-bit logical operations on inte- 
ger or byte data and returning integer results. Do not con- 
fuse these functions with Boolean type operators. 


LAND 
LOR 
LXOR 


LNOT 


Calculates the logical AND of two values. 
Calculates the logical OR of two values. 


Calculates the logical EXCLUSIVE OR of two 
values. 


Calculates the logical NOT of a value. 


Functions returning a result of type string 


CHR$ 


DATE$ 


LEFT$ 


RIGHT$ 


MID$ 


STR$ 
TRIM$ 


Returns the character having a specified ASCII 
value. 


Returns the system’s current date and time. 


Returns the specified number of characters 
beginning at the leftmost character of the 
specified string. 


Returns the specified number of characters 
beginning at the rightmost character of the 
specified string and counting backward. 


Returns the specified number of characters 
starting at the specified position in a string. 


Converts numeric type data to string type. 


Removes trailing spaces from the specified 
string. 


Functions returning Boolean values 


TRUE 
FALSE 
EOF 


Always returns TRUE. 
Always returns FALSE. 


Tests for the end of a disk file. Returns TRUE 
when the end of the file occurs. 


Chapter 8 


Disk Files 


When you tell OS-9 or BASICO9 to store (save) data on a disk, it 
stores the data in a logical block called a file. The term logical 
means that, although the system might store portions of a file’s 
data in several different disk locations, it keeps track of every 
location and treats the scattered data as though it occupied a 
single block. It does this automatically and you never need to 
worry about how the data is stored. File data can be binary 
data, textual data (ASCII characters), or any other useful 
information. 


Because OS-9 handles all hardware input/output devices (disk 
drives, printers, terminals, and so on) in the same manner, you 
can send data to any of these devices in the same way. This 
means you can send the same information to several devices by 
changing the path the data follows. For example, you can test a 
procedure that communicates with a terminal by transferring 
data to and from a disk drive. 


BASICO9 normally works with two types of files—sequential 
files and random access files. The following chart shows file- 
access options, their purposes, and the keywords with which to 
use them: 


Types of Access for Files 


Access Function Use with 

Type 

DIR Opens a directory file for reading. OPEN 
Use only with READ. 

EXEC Specifies that the file to open or OPEN 
create is in the execution directory, CREATE 
rather than the data directory. 

READ Lets you read data from the OPEN 
specified file or device. CREATE 

WRITE Lets you write data to the specified OPEN 
file or device. CREATE 

UPDATE Lets you read data from and write OPEN 
data to the specified file or device. CREATE 
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Sequential Files 


Sequential files send or receive (WRITE or READ) textual data 
in order, the second item following the first, and so on. You can 
access sequential data only in the same order as you originally 
stored it. To read from or write to a particular section of a file, 
you must first read through all the preceding data in the file, 
starting from the beginning. 


BASICO9 stores sequential file data as ASCII characters. Each 
block of data is separated by a delimiter consisting of a carriage- 
return character (ASCII Character 13). Because BASICO9 uses 
this delimiter to determine the end of a record, sequential files 
can contain records of varying length. 


Use the WRITE and READ commands to store and retrieve data 
in sequential files. A WRITE command causes BASICO9 to 
transfer specified data to a specified file, ending the data with a 
carriage return. A READ command causes BASICO09 to load 
from the specified file the next block of data, stopping when it 
reaches a carriage return. 


Sequential File Creation, Storage, and Retrieval 


BASICO9 uses the CREATE command to establish both sequen- 
tial and random access files. A CREATE statement contains: 


@ The keyword CREATE. 


@ A path number variable in which BASICO9 stores the 
number of the path it opens to the new file. 


@ A comma, followed by the name of the file to create. 


e An optional colon, followed by the access mode. If you do 
not specify an access mode, BASICO9 automatically 
opens the created file in the UPDATE mode. 
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The following procedure shows how to create a file and write 
data into it: 


) PROCEDURE makefile 


LIDIM PATH: BYTE (+ establishes a variable 

LIREM for the path number to the file 
LICREATE #PATH, "test": WRITE (+ creates the file TEST 

LIWRITE #PATH,"This is a test" (* writes data to the file 

LIWRITE #PATH,"of sequential files."(* writes another line of data 
LICLOSE #PATH (+ closes the path to the file 
PHELL. “List teat" (* displays the file contents 

LIEND 


The first line of the procedure dimensions a variable (Path) to 
hold the number of the path that CREATE opens. This variable 
should be of byte or integer type. 


When you establish a new file with CREATE, you automatically 
open a path to the file. You do not need to use the OPEN 
command. 


The preceding procedure writes two lines into a file named Test. 

a It then closes the path and uses the OS-9 LIST command to dis- 
play the contents of the newly created file. You see that the data 
is successfully stored on disk. 


The next procedure shows how to reopen an existing file for 
sequential access, read the contents of the file, and append data 
to the end of the file. 


The only way to move the file pointer to the end of a sequential 
file is to read all the data already in the file. Once the pointer is 
at the end of the file, you can add data. 


PROCEDURE append 


LIDIM PATH: BYTE (* dimension variable to hold the number of the 
LIREM path to the opened file. 
CIOPEN #PATH,"test": UPDATE (* open file for reading and writing. 
LIREAD #PATH, line$ (+ read the first element of the file. 
LIREAD #PATH, line$ (+ read the next (the last) element. 
CIWRITE #PATH,"This is a test" (* write one new line to the file. 
=) LIWRITE #PATH,"of appending to a sequential file." (* write another. 
—— LICLOSE #PATH (+ close the path. 
Lionece. “Liat TEST? (+ display the file with the new lines. 
LIEND 
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Because the Test file already exists, this procedure uses OPEN 
to establish a path to the file. It uses the UPDATE mode of file 
access because it needs to both read from and write to the file. 


The two READ statements read the file’s contents and, as a 
result, move the file pointer to the end of the file. The WRITE 
statements then append two new lines. After closing the path, 
the procedure calls on the OS-9 LIST command to display the 
contents of the file, with its appended lines. 


Changing Data in a Sequential File 


You can also change data anywhere in a sequential file. How- 
ever, if your changes are longer than the original data, the oper- 
ation destroys part of the file. To change data in a sequential 
file, read the data preceding what you want to change, and write 
the new data to the file in this manner: 


PROCEDURE replace 
LIDIM PATH: BYTE 
LIOPEN #PATH,"test™:UPDATE 


LIREAD #PATH, line$ 

LIREAD #PATH, lines 

LIWRITE #PATH,"Let’s put new" (+ write over existing 3rd and 
LIWRITE #PATH,"words into the old sequential file.’’ (+ 4th lines. 
LICLOSE #PATH 

SnecL METS TESTS 


LIEND 


Notice that the total amount of data in the two new lines is 
exactly the same as in the two old lines. You can replace an 
existing line with fewer characters by padding the new data 
with spaces. However, if you try to replace existing lines with 
longer lines, the new lines write over and destroy other data in 
the file. 
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INPUT and Sequential Files 


Although you can also use the INPUT command with sequential 
files, doing so might put unwanted data into them. When a pro- 
cedure encounters INPUT, it suspends execution and sends a 
question mark (?) to the screen. This feature makes INPUT both 
an input and output statement. Therefore, if you open a file 
using the UPDATE mode, INPUT writes its prompts to the file, 
destroying data. If you specify text to be displayed with the 
INPUT command, INPUT writes this text to the file also. 


Random Access Files 


Random access files store data in fixed- or equal-length blocks. 
Because each record in a specific file is the same size, you can 
easily calculate the position of a record. 


For instance, suppose you have a file with a record length of 50- 
bytes (or characters). To access Record 10, multiply the record 
number (10) by the record length (50) and move the file pointer 
to the calculated position (500). 


A random access file sends and receives data (using PUT and 
GET) in a binary form, exactly as BASICO9 stores it internally. 
This feature minimizes the time involved in converting the data 
to and from ASCII representation, as well as reducing the file 
space required to store numeric data. You position the random 
access file pointer using SEEK. Compared to sequential file 
access, random file access using GET and PUT is very fast. 


Using random access commands, you can store and retrieve indi- 
vidual bytes, strings of bytes, individual elements of arrays or 
total arrays with one PUT or GET command. When you GET a 
structure, you recover the number of bytes associated with that 
type of structure. 


This means when you GET one element of byte type data, you 
read one byte. When you GET one element of real type data, you 
read five bytes. If you GET an array, you read all the elements of 
the array. This potential for reading entire arrays at once can 
greatly speed disk access. 


As well as moving the file pointer to the beginning of individual 
records, you can also move it to any position within a record and 
begin reading or writing one or more bytes from that point. 
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Creating Random Access Files 


You create and open random access files in the same way you 
create and open sequential files. The only differences are in the 
commands you use to store and retrieve the data and in the 
manner you keep track of where elements, or records, of a file 
begin and end. 


Before you can write data to a random access file, you must 
either CREATE it or open it in the WRITE or UPDATE mode. 
Once you have a path open to an existing file, use PUT to write 
data into the file. If you open the file in the READ or UPDATE 
mode, you can then use the GET command to retrieve data from 
the file. 


The PUT command can use only one parameter, the name of the 
data element to store. The parameter can be a string, a variable, 
an array, or a complex data structure. 


Before storing data, you must devise a method to store it in 
blocks of equal size. Knowing the unit size lets you later retrieve 
the data in its original form. The following procedure shows one 
way to do this: 


PROCEDURE putget 
OREM This procedure creates a file named Test1, reads 10 data lines, 
CREM PUTS them into the file, then closes the file. Next it 

DREM opens the file in the READ mode, GETS stored lines and lists 


DREM them on the display screen. 


CIDIM LENGTH: BYTE 
CIDIM NULL: STRING(25]} 
DDIM LINE:STRING(25] 
KIDIM PATH: BYTE 
LILENGTH=25 

UNULL="" 

CIBASE 9 

CON ERROR GOTO 18 

LIDELETE "testi" (+ if the file exists, delete it. 
1@L0N ERROR 


CICREATE #PATH,"testi":WRITE (* create a file named testi. 


CIFOR T=0 10 9 

LISEEK #PATH,LENGTH#T (+ find beginning of each file. 
CIREAD LINE$ (+ read a line of data. 

LIPUT #PATH,LINE$ (* store the line in the file. 
LINEXT T 
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TICLOSE #PATH (+ close the file. 

LIOPEN #PATH,"test1":READ (+ open the file for reading. 

CIFOR T=@ T0 9 

CISEEK #PATH,LENGTH#T (+ find the beginning of each file. 
LIGET #PATH,LINE (# gel a line from the file. 
LIPRINT LINE (+ display the line. 

CINEXT T 

LICLOSE #PATH (+ close the file. 

CEND 


KIDATA "This is test line #1" 
CIDATA "This is test line #2" 
OIDATA "This is test line #3" 
KIDATA "This is test line #4" 
LIDATA "This is test line #5" 
KIDATA "This is test line #6" 
LIDATA "This is test line #7" 
LIDATA "This is test line #8" 
DDATA "This is test line #9" 
DDATA "This is test line #10" 


This procedure creates a file named Test1. The variable named 
Length stores the length of each line in the file (25 characters). 
The string variable Null, is a string of 25 space characters. The 
variable Line contains the data to store in each element (record) 
in the file. The variable Path stores the path number of the file. 


Next, the procedure contains an ON ERROR routine that deletes 
the file Test1, if it already exists. Without this routine, the pro- 
cedure produces an error if you execute it more than once. 


Next, the routine uses CREATE to open the file Test1. The line 
SEEK #PATH, LENGTH*T sets the file pointer to the proper loca- 
tion to store the next line. Because Length is established as 25, 
the file lines are stored at 0, 25, 50, 75, and so on. 


After the routine initializes storage space, it begins to store 
data by reading the procedure data lines one at a time, seeking 
the proper file location, and putting the data into the file. After 
storing all 10 lines, it closes the file. 
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The last part of the routine opens the new file, uses the same 
SEEK routine to position the file pointer, and reads the lines 
back, one at a time, to confirm that the store routine is 
successful. 


The next short routine shows how you can use a procedure to 
read any line you select in the file, without reading any preced- 
ing lines: 


PROCEDURE randomread 
LIDIM LENGTH: BYTE 
CIDIM LINE: STRING([25] 
LIDIM SEEKLINE:BYTE 
DDIM PATH:BYTE 
KILENGTH=25 


LIOPEN #PATH,"test1":READ (# open the file for reading. 
CILOOP 

INPUT "Line number to display...",SEEKLINE (* type a line to get. 
DIEXITIF SEEKLINE>1@ OR SEEKLINE<1 THEN (* test if record is valid. 


DENDEXIT (+ exit loop if not. 

LISEEK #PATH, (SEEKLINE-1)*LENGTH (+ find the requested record. 
LIGET #PATH,LINE (# read the record, 

DPRINT LINE (+ display the record, 

DPRINT 

LIENDLOOP 

LIPRINT "That’s all ....... a (* end session, 

OICLOSE #PATH (+ close path. 

DEND 


The procedure asks for the record number of the line to display. 
When you type the number (1-10) and press (ENTER), SEEK moves 
the file pointer to the beginning of the record you want, GET 
reads it into the variable Line, and PRINT displays it. The cal- 
culation (SEEKLINE-1)*LENGTH determines the beginning of 
the line you want. If you type a number outside the range of 
lines contained in the file (1-10), the procedure drops down to 
Line 100 and ends. 


By changing this procedure slightly, you can replace any line in 
the procedure with another line. The altered procedure below 
demonstrates this: 
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PROCEDURE random__replace 
LIDIM LENGTH: BYTE 

LIDIM LINE: STRING(25] 

LIDIM SEEKLINE: BYTE 
LIDIM PATH: BYTE 


LILENGTH=26 


KOPEN #PATH,"testi":UPDATE(* open the file. 
LILOOP 


KINPUT "Line number to display...",SEEKLINE (+ type record to find. 
DEXITIF SEEKLINE®1@ OR SEEKLINE<1 THEN (* test if valid number. 


LIENDEXIT (+ exit loop if not 

OSEEK #PATH,(SEEKLINE-1)#LENGTH (# find the requested record. 
LIGET #PATH,LINE (+ get the data. 

LIPRINT LINE (+ print the record. 

LIPRINT 


KINPUT "Type new line... ",LINE (# type a new line. 
CSEEK #PATH,(SEEKLINE-1)#LENGTH (* find beginning of the record. 


LIPUT #PATH,LINE (* store the new line. 
CIENDLOOP (+ do it all again. 
PIPRING “That's al) sateisa 4 (+ terminate procedure. 
CICLOSE #PATH (+ close path. 

CEND 


This time, the file is opened in the UPDATE mode to allow both 
reading and writing. You type the line you want to display. A 
prompt then asks you to type a new line. The procedure 


exchanges the new line for the original line, and stores it back in 
the file. 


Using Arrays With Random Access Files 


BASIC09’s random access filing system is even more impressive 
when used with data structures, such as arrays. Instead of using 
a loop to store the 10 lines of the Random_replace procedure, 
you could store them all at once, into one record, using an array. 
The following procedure illustrates this: 
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PROCEDURE arraywrite 

LIDIM LENGTH: BYTE 

LIDIM LINE: STRING(25] 

CIDIM RECORDC18):STRING(25] 
LIDIM PATH: BYTE 

LILENGTH=25 


LION ERROR GOTO 18 
LIDELETE "testi" 
18LJON ERROR 


LICREATE #PATH,"test1":WRITE 
LIBASE @ 


LIFOR T=8 TO 9 
LIREAD RECORD(T) 
LINEXT T 


LISEEK #PATH, 0 
LIPUT #PATH,RECORD 
LICLOSE #PATH 


LOPEN #PATH,"testi":READ 
LIFOR T=8 TO 9 

LISEEK #PATH, LENGTH#T 
LIGET #PATH,LINE 

LIPRINT LINE 

LINEXT T 

PICLOSE #PATH 

LIEND 


DIDATA "This is test line #1" 
OIDATA "This is test line #2" 
ODATA "This is test line #3" 
DDATA "This is test line #4" 
ODATA "This is test line #5" 
CIDATA "This is test line #6" 
ODATA "This is test line #7" 
CIDATA "This is test line #8" 
ODATA "This is test line #9" 
UIDATA "This is test line #10" 
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(* delete Test! if it exists. 


( 


od 


create Testi, 


(* Read data lines into RECORD array, 


(+ set pointer to beginning of file. 
(* store the entire array into file, 
(+ close path to file. 


(+ open the file to read, 
(* find each element. 


(+ read an element. 
(+ print the element. 
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This procedure reads the 10 lines into an array named Records. 
Then it places the entire array in the Testl file, using one PUT 
statement. To show that the structure of the file is still the 
same, the original FOR/NEXT loop reads the lines, one at a 
time, and displays them. 


Notice that, because you need to write only one element, you can 
set the file pointer to 0 (SEEK #PATH,@). You can rewind a file 
pointer (set it to 0) at any time in this manner. 


You could save additional programming space by also reading the 
10 lines back into memory as an array. The following procedure 
uses a new array, Readlines, to call the file back into memory, 
and displays the lines. 


PROCEDURE arrayread 

LIBASE @ 

LIDIM READLINES(10):STRING(25] 
LIDIM PATH: BYTE 


KOPEN #PATH,"test1":READ (+ open file. 
LIGET #PATH,READLINES (+ read file into array, 
CICLOSE #PATH 


LIFOR T=@ 10 9 

LIPRINT READLINES(T) (+ print each element of the array. 
LINEXT T 

LIEND 


Using Complex Data Structures 


In the previous section, you stored and retrieved elements of an 
array that were all the same size, 25 characters. Often you need 
to store elements of varying sizes, such as when you create a 
data base program with several fields in one record. 


The following examples create a simple inventory system that 
requires a random access file having 100 records. Each record 
includes the name of the item (a 25-byte string), the item’s list 
price and cost (both real numbers), and the quantity on hand (an 
integer). 


BASIC09 Reference 


First, you use the TYPE command to define a new data type 
that describes such a record. For example: 


TYPE. TNVezTTEM*NAMESSTRINGL 2515 LIST,cCOSTsREAL: 
aT Ys INTEGER 


Although this statement describes a new record type called 
Inv_item, it does not assign variable storage for the record. The 
next step is to create two data structures: an array of 100 rec- 
ords of type Inv_item named Inv_array and a working record 
named 

Work_rec. The following lines do this: 


DIM INV_ARRAYC108):INV_ITEM 
DIM WORK__REC: INV_ITEM 


To determine the number of bytes assigned for each type, you 
can use BASICO09’s SIZE command. SIZE returns the number of 
bytes assigned to any variable, array, or complex data structure. 
For example, the command line SIZECWORKI__REC) returns the 
number 37. The command SIZECINV_ARRAY) returns the num- 
ber 3700. 


You can use SIZE with SEEK to position a file pointer to a spe- 
cific record’s address. 


The following procedure creates a file called Inventory and 
immediately initializes it with zeroes and null strings. Five 
INPUT lines then ask you for a record number and the data to 
store in each field of the record. You can fill any record you 
choose, from 1 through 100. 


When one record is complete, the procedure uses PUT to store 
the record. Then, it asks you for a new record number. If you 
wish to quit, enter a number either larger than 100 or smaller 
than 1. 


PROCEDURE inventory 

LIREM Create a data type consisting of a 25-character name field, 
DREM a real list price field, a real cost field, and an integer 
OREM quantity field. 

LITYPE INV__ITEM=NAME:STRING(25]; LIST,COST:REAL: QTY: INTEGER 


CIDIM INV__ARRAY(100):INV__ITEM (# dimension an array using new type. 
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CIDIM WORK__REC: INV__ITEM 
CREM (* dimension a working variable of the new type. 
LIDIM PATH: BYTE 


LION ERROR GOTO 10 
LIDELETE "inventory" 
{@QJ0N ERROR 


LICREATE #PATH, "inventory" (+ create a file named Inventory. 
LIWORK__REC.NAME="" " (+ set all data elements to null or @. 
LIWORK__REC.LIST=0 

LIWORK__REC.COST=0 

LIWORK__REC.QTY=0 

LIFOR N=1 TO 108 

LIPUT #PATH ,WORK__REC 

LINEXT N 


LILOOP 

LIINPUT "Record number? ",RNUM (# enter number of record to write. 
LIF RNUM<1 OR RNUM>10@ THEN (* check if number is valid. 
LIPRINT 

LIPRINT "End of Session" (* if not, end session. 

LIPRINT 

LICLOSE #PATH 

LIEND 

LIENDIF 

KUINPUT "Item name? ",WORK__REC.NAME (+ type data for record, 
DINPUT "List price? ",WORK__REC.LIST 

KIINPUT "Cost price? ",WORK_REC.COST 

KIINPUT "Quantity? ",WORK_REC. QTY 

LISEEK #PATH, CRNUM-1)#SIZECWORK__REC) (# find record. 

LIPUT #PATH ,WORK__REC (# write record to file. 
HIENDLOOP 


Notice that the INPUT statements reference each field sepa- 
rately, but the PUT statement references the record as a whole. 


The next procedure lets you read any record in your Inventory 
file, and displays that record. If you ask for a record you have not 
yet filled with meaningful data, the display consists of a null 
string and zeroes. 


PROCEDURE readinv 
LITYPE INV__ITEM=NAME:STRING([25]; LIST,COST:REAL: QTY:INTEGER 
LIDIM WORK__REC: INV__ITEM 
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LIDIM PATH:BYTE 

LJOPEN #PATH, "INVENTORY": READ 
LILOOP 

CIINPUT "Record number to display? ",RNUM 
CIF RNUM<1 OR RNUM>100 THEN 

DPRINT “End of Session" 

DIPRINT 

LICLOSE #PATH 

LIEND 

LIENDIF 

LISEEK #PATH, C(RNUM-1)#SIZE(WORK__REC) 
LIGET #PATH,WORK__REC 

LIPRINT "#" "Item", "List Price","Cost Price", "Quantity" 

LIPRINT "nnn nn nnn nn nnn nnn nnn renee nnn nner nn nnn nnn en nen nee en en nee e eee ee 


LIPRINT RNUM,WORK__REC.NAME ,WORK__REC.LIST,WORK__REC. COST ,WORK__REC. QTY 
LIPRINT 

LIENDLOOP 

LIEND 


This procedure accesses the file one record at a time. It is not 
necessary to do so. You can read the entire file into memory at 
once by dimensioning an inventory array and getting the whole 
file into it: 


LITYPE INV__ITEM=NAME:STRING(25]; LIST,COST:REAL; QTY: INTEGER 
LIDIM INV__ARRAY(100): INV__ITEM 

LISEEK #PATH,@  (#rewind the file) 

LIGET #PATH, INV__ARRAY 


The examples in this section are simple, yet they illustrate the 
combined power of BASICO9 complex data structures and the 
random access file statements. They show that a single GET or 
PUT statement can move any amount of data, organized in any 
way you want. Other advantages are of using complex data struc- 
tures are: 


@ The procedures are self-documenting. You can see easily 
what a procedure does because its structures can have 
descriptive names. 


@ Execution is extremely fast. 


@ Procedures are simple and usually require fewer state- 
ments to perform I/O functions than other BASICs. 
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@ The procedures are versatile. By creating appropriate 

data structures, you can read or write almost any kind 

‘- of data from any file, including files created by other pro- 
<0 grams or languages. 


Chapter 9 


Displaying Text and Graphics 


BASICO9 has three levels of graphics capabilities. The first and 
third levels can include both graphics designs and text. The sec- 
ond level can display only graphics designs. 


ASCII Codes 


For low-resolution text screens and high-resolution text and 
graphic screens, BASICO9 uses ASCII (American Standard Code 
for Information Interchange) codes to represent the common 
alphanumeric characters. ASCII is the same code that most 
small computers use. 


A table of the standard codes follows: 


Table 9.1 
BASIC09 ASCII Codes 0-127 
Low- and High-Resolution Screens 


Character Decimal Code Hexadecimal Code 
03 03 
8 O8 
9 O9 
10 OA 
CLEAR 12 OC 
13 OD 
Space 32 20 
! 3a PA 
" 34 22 
# 35 23 
$ 36 24 
% 37 20 
& 38 26 
39 27 
( 40 28 
) 41 29 
* 42 2A 
-- 43 2B 
44 2C 
. 45 2D 
46 2E 
/ 47 2F 
0 48 30 


9-1 


BASICO9 Reference 


Character 


OMmoNIHILhWNrFR 


SSI CHMADVOAZSOCAGH TEOMA OGCAOWPOe~rV il Av - 


xX 
¥ 
Z 
[ (GH) 
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Decimal Code 


49 
50 
ol 
o2 
o3 
o4 
DD 
56 
o7 
08 
o9 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
12 
73 
74 
75 
76 
T¢ 
78 
2 
80 
81 
82 
83 
84 
85 
86 
87 
88 
89 
90 
v1 


Hexadecimal! Code 


31 
32 
33 
34 
35 
36 
37 
38 
39 
3A 
3B 
3C 
3D 
3E 
oF 
40 
Al 
42 
43 
dd 
45 
46 
47 
48 
AQ 
4A 
4B 
4C 
AD 
4K 
AF 
50 
ol 
O2 
O3 
o4 
ye) 
56 
o7 
08 
59 
5A 
5B 
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Character Decimal Code Hexadecimal Code 
Fa \. ((SHIFT ](CLEAR }) 92 5C 
| ] ((SHIFT }(>)) 93 5D 
rN 94 5E 
—> ((SHIFT ]{ 4 }) 95 bE 
~ 96 60 
a 97 61 
b 98 62 
¢ 99 63 
d 100 64 
e 101 65 
f 102 66 
g 103 67 
h 104 68 
i 105 69 
j 106 6A 
k 107 6B 
] 108 6C 
m 109 6D 
n 110 6E 
cy O Lid 6F 
p 112 70 
q 113 Tl 
r 114 12 
S 115 73 
t 116 74 
u L17 10 
V 118 76 
w 119 (ei 
x 120 78 
y 121 79 
Z 122 TA 
{ 123 7B 
| 124 iG 
} 125 TD 
% 126 7E 
— 127 7F 


>» You can generate the characters in this chart by pressing the 
appropriate key, or you can generate them from BASICO9 using 
the CHR$ function. 
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Low-Resolution Graphic Characters 


In addition to alphanumeric characters, low-resolution graphics 
also offers graphic characters. Generate these characters by 
pressing at the same time you press a keyboard character. 
The graphics character codes are in the range 128-255. 


Pressing while pressing another key, causes OS-9 to add 
128 to the ASCII value of the second key. (For the technically 
minded, OS-9 sets the high bit of the character code.) Therefore, 
if you press [A], you produce graphics character 193. You can 
also generate graphics characters from BASICO9 using the 
CHR$ function, and you can PRINT them in the same manner 
as other characters. 


Low-level graphics characters follow a pattern that repeats every 
16 characters. Table 9.2 shows the first set of graphic characters, 
128-143. Subsequent characters produce the same series of con- 
figurations but display in different colors, as shown in Table 9.3. 


Table 9.2 
Low-Resolution Graphic Character Set 


Character Code Character Code Character Code Character Code 


128 136 140 
129 133 137 141 
130 a” 134 138 142 
131 alll 135 | 139 | | 143 
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Table 9.3 
Low-Resolution Graphics Color Set 


ASCIT Code Graphics Block Color 


128 - 143 Black and Green 

144 - 159 Black and Yellow 

160 - 175 Black and Blue 

176 - 191 Black and Red 

192 - 207 Black and Buff 

208 - 223 Black and Light Blue 

224 - 239 Black and Cyan 

240 - 254 Black and Orange 
Zoo Green 


Within each color set, you can easily calculate the number for a 
particular character. For instance, suppose you want to print a 
character that has orange upper left and lower right corners. Pic- 
ture the character divided into four sections, numbered as 
follows: 


To calculate a character that has orange at Sections 8 and 1, add 
the section values to the first value in the orange group, 240, 
like this: 


240 + 8+ 1 = 249 
Character 249 is what you want. 


The following diagram shows how you might block out a large 
letter O on the screen. The shaded portions of the characters are 
colored. The unshaded portions are black. In this case we want 
the colored portions to be green (the same color as the screen). 
You can do this using the color set 128 - 143. 
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Because Section 1 in the upper left character is to be colored, 
add 1 to the initial character value of 128. The first character 
value is 129. Moving right, Sections 2 and 1 are colored in the 
second character. Add 3 to 128 to get a second character value of 
131. Calculate all 15 characters in this manner. 


You could create a letter O in a BASICO9 procedure by printing 
each of the five rows of three characters. You could use DATA 
lines to store the ASCII codes for each character, then use loops 
to read and display the characters they represent. 


Although low-level graphics is very rough, it can be useful, and 
it lets you mix graphics with text. 


The following procedure not only creates the letter O, it adds the 
letter S and the number 9 to display the name of your operating 
system. 
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PROCEDURE os9prog 
ODIM DAT: INTEGER 
TPRINT CHR$C€12) 
OPRINT 

OPRINT 

OPRINT 

OFOR Z=1 TO 5 


UPRINT TABC18); 

UFOR T=1 TO 12 

UREAD DAT 

UIPRINT CHRS$CDAT); 

IAEA OT 

PRINT 

INERT 32 

LEND 

ORT: TES. 1St 41 e0y TAS. 1203 1319 1.31 o 1 4Sg Tees 13ST 4 rats 
143 

LOATA, 1334 14351384 17935733514935174934 1934132, 190s 1se4 
143 


IDATO 133314351384 14341-3245 1.405 140514541314 131413905 
o-~ 143 

UDATA 1334143; 13851435133 4131413051 435414351934.1 36% 

143 

UDATA: tae4 1905136, 149351404140, 13651493,143,19355138, 

143 
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Special Characters in High-Resolution 


High-resolution graphics does not have graphic characters but it 
does have other international and special characters. These char- 
acters are represented by ASCII codes 128 through 159 as shown 
in the following table: 


Table 9.4 
High-Resolution Special Characters 
Hex Decimal Hex Decimal 
Character Code Code Character Code Code 
C 80 128 6 90 144 
u 81 129 ae 91 145 
é 82 130 my 92 146 
a 83 les w! 6 93 147 
a 84 132 6 94 148 
a 85 133 Dg 95 149 
a 86 134 a 96 150 
C 87 135 u 97 151 
é 88 136 Q 98 152 
é 89 137 O 99 153 
é 8A 138 O 9A 154 
i 8B 139 § 9B 155 
n 8C 140 £ 9C 156 
Ff) 8D 141 = 9D L57 
A 8E 142 ° 9K 158 
A 8F 143 f OF 159 


Medium-Resolution Graphics 


For more sophisticated graphics operations, OS-9 has built-in 
graphics interface modules that provide a convenient way to 
access the graphics and joystick functions of the Color Computer 
3. The required module for medium-resolution graphics is named 
GFX. It must be in your execution directory or resident in mem- 
ory when called by BASICO9. 


You can either install GFX in memory using the LOAD com- 
mand, or wait until BASICO9 calls it for a graphics function. 
Once loaded, GFX resides in memory until you remove it using 
the OS-9 UNLINK command or the BASICO9 KILL command. 
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GFX has a number of functions that you pass to it as parame- 
ters with the RUN statement. For instance, the following state- 


ment clears the current graphics screen: 


RUN GFXC™CLEAR") 


Other tasks need such parameters as position, color, and size. 
The following is a quick reference to all of the GFX functions. 
Each is explained in detail later: 


Function 


ALPHA 


CIRCLE 


CLEAR 


COLOR 


GCOLR 


GLOC 


JOYSTK 


LINE 


MODE 


MOVE 


Purpose 


Sets the screen to the 
alphanumeric mode. 


Draws a circle. 


Clears the screen to a 
color. 


Changes the foreground 
and background colors. 


Reads a pixel’s color. 


Returns a video display 
address. 


Returns the joystick 
button and X- and Y- 
coordinate status. 


Draws a line. 


Switches the screen 
between alphanumeric 
and graphics, sets the 
graphics screen color. 


Positions the invisible 
graphics cursor. 


Parameters 


None. 


Radius, optional X- and 
Y-coordinates, and color. 


Optional color for screen. 


Foreground and 
background colors. 


Names of variables in 
which to store optional 
X- and Y-coordinates. 


None. 


Names of variables in 
which to return the 
values. 


Ending X- and Y- 
coordinates, optional 
beginning coordinates, 
optional color. 


Format, Color. 


X- and Y-coordinates. 
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Function Purpose Parameters 

POINT Moves graphics cursor X- and Y-coordinates 
and sets a point. and optional pixel color. 

QUIT Returns screen to None. 


alphanumeric mode. 
Deallocates graphics 
memory. 


Formats and Colors 


In medium-resolution graphics, you have a choice of two formats. 
Format 0 provides 256 horizontal points by 192 vertical points. In 
this format, you can have only two colors on the screen at a time. 


Format 1 provides a 128 by 192 point screen and a maximum of 
four colors on the screen at a time. OS-9 medium-resolution 
graphics treats the screen as if it were a grid, with coordinate 
0,0 at the lower left corner as shown in the following illustration. 
All points on the grid are positive. 


OS a ea 
0, X-coordinate 


BASICO9 defines colors with numbers or color codes. Many GFX 
functions allow or require color codes as parameters. BASICO9 
also divides the color codes into color sets. Specifying a color code 
outside the current color set automatically initializes the new 
set. 
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Back- Fore- 
ground | ground 


Format 0 


Fore- 
ground | ground 


Black 
Green 


Buff 
Cyan 

Magenta 
Orange 


Black 
Dk Green 
Md Green 
Lt Green 


Table 9.5 


Use the preceding charts to chose colors for those functions that 
let you specify foreground or background colors. For instance, to 
initialize a Format 1 graphics screen with a green background 
and a red foreground, you type: 


run gfxC"mode",1,3) 


The following reference section describes all the medium-resolu- 
tion graphics functions, and provides examples and sample pro- 
grams. To understand the organization of the commands 
reference, see “The Syntax Line” in Chapter 11. 
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The Draw Pointer 


Medium-resolution graphics uses a draw pointer, or invisible 
graphics cursor, to determine what area of the screen is affected 
by graphics operations. When you establish a graphics screen, 
the draw pointer is located at coordinates 0,0. Some graphic 
functions automatically change the pointer location on the 
screen. For instance, the LINE function moves the draw pointer 
from the beginning coordinates to the end coordinates. 


Because some functions begin at the draw pointer, you need to 
keep track of its location and make certain it is placed properly. 
Use the MOVE function to set the draw pointer to new locations. 
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ALPHA Select alphanumeric screen 


Syntax: RUN GFX(“ALPHA”) 


Function: Switches from the graphics screen to the alphanu- 
meric (text) screen. The current graphics screen remains 
intact. 


Parameters: None 


Examples: 
RUN GFXC™ALPHA") 


Sample Program: 


This procedure lets you choose to draw a circle or rectangle of 
the size you select. Once you choose the shape and size, it uses 
the MODE function to select a graphics screen. When the shape 
is complete, you press to return to a text screen. The pro- 
cedure uses the ALPHA function to return to the original menu. 


PROCEDURE alpha 

DDIM XCOR.YCOR.SIDE1,SIDE]2], RADIUS; 7%. ¥,2¢INTEGER 
ODIM RESPONSE:STRING([1] 

18 REPEAT 

SHELL. “DISPLAY #c™ 

OPRINT "Do you want to draw" 

UPRINT “13 A rectangle” 

LPRINT “223. 4 eirele”™ 


OPRINT " -Press 1 or 2...""3 

UGET #@,RESPONSE 

OPRINT 

ULF RESPONSE="1" THEN 

INPUT “Lengtin OF Sid@ 156." ,Si1DEt 
DENPUT. “Lengin of Side 255.%,S1DE2 


URUN GFXC™MODE",@,9) 

URUN GFXC™CLEAR") 

UXCOR=10 

LIYCOR=19 

LRUN GEXC™LINE”, XCOR; YCORsXCOR+S1DE1s YCOR 1.2 


BASICO9 Reference 


IRUN GEAC™LINE”, XCGR*#SIDET, YCOR, XCUR*#S IDET. YOUR* 
2IDEG +42 

DRUN: GFXCeLINE”’  XCOR*S IDET, YCOR+S DES, XCUR, YCUR* 
SLVee ae 

DRUN GFXC "LINE, XCOR;, YCOR+SI DES, XCOR, YCOR,1 9 
UINPUT RESPONSE 


JEL SE 
He KESPOnSc ="2”"- Taen 
UINPUT “What radius?...™",RADIUS 


URUN GFXC™MODE",@,1) 

URUN GFXC"™CLEAR") 

ORUN GFXC™CIRCLE”,128,98,RADIUS) 
LISPUT RESPONSE 

LENDIF 

UENDIF 

LJUNTIC RESPONSE <3*°7" AND. RESPONSE<> "2" 
LIRUN GFXC™ALPHA") 

UGOTO 18 

WEND 
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CIRCLE Draw a circle 


Syntax: RUN GFX(“CIRCLE”[,xcor,ycor],radius [,color]) 


Function: Draws a circle of a given radius. If you do not spec- 
ify a color, BASICO9 uses the current foreground color. If you 
do not specify X- and Y-coordinates, CIRCLE uses the current 
graphics cursor position as the circle’s center. 


Parameters: 
radius The radius of the circle you want to draw. 
color The code of the color you want the circle to be. 
See the chart earlier in this section for color 
information. 
xcor,ycor The X- and Y-coordinates for the center of the 
circle. Specifying coordinates outside the X- 
coordinate range of 0-255 or outside the Y- 
coordinate range of 0-191 causes an error. 
Examples: 


RUN GFXC™CIRCLE",100) 
RUN GFXC™"CIRCLE",100,3) 
BUN GEAC™CUTROULE" 125. 180,188) 


RUN GFXC™CIRCLE™ 125,180,108, 2) 


Sample Program: 


This procedure uses CIRCLE to draw and erase a circle. The 
location of the circle changes before each draw/erase operation, 
causing the circle to move. When it hits the edge of the screen, 
it reverses its direction at a random angle and bounces. 


PRUCEDURE cireles 

ODIM RADIUS,XCOR,YCOR: INTEGER 
UDIM XTEMP,YTEMP: INTEGER 

LIDIM PATH1,PATH2@: INTEGER 

UDIM FLAG: INTEGER 
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LFLAG=1 

UXCOR=5 

UYCOR=5 
UPATH1=RNDC15)+2 
UIPATH2=RNDC18@)+2 
UXTEMP=249 
LYTEMP=185 

URUN GFXC™MODE",@,1) 
URUN GFXC"™CLEAR") 
UFOR T=1 TO 209 
OWHILE XCOR<25@ AND XCOR>4 AND YCOR<186 AND YCOR>4 
DO 

UIRUN. GCF XAC’™CTROLE*. 2TEMP, YIEMP 3 5.82 
OIRUN OF XC™CIRCLE™, XCOR, YCOR,3319 
UXTEMP=XCOR 
LYTEMP=YCOR 
UXCOR=XCOR+PATH1 
LYCOR=YCOR+PATH2 
UENDWHILE 

LIPATH1 =RNDC15)+2 
UPATH2=RNDC19)+2 

DIF XCOR>249 THEN 
UxXCOR=249 

DENDIF 

HIF XCOR<S THEN 
UXCOR=5 

LJENDLF 

DIF YCOR>18S THEN 
UYCOR=185 

UENDIF 

HIF YCOR<S THEN 
UYCOR=5 

JEND LF 

LIFLAG=FLAG*-1 

DIF FLAG<@ THEN 
LIPATH1 =PATH1*-1 
UPATH2=PATH2+*-1 
UENDIF 

UNEXT T 

UEND 
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CLEAR Clear the screen 


om 

Syntax: RUN GFX(“CLEAR”(,color)) 

Function: Clears the current graphics screen. If you do not 
specify a color, CLEAR sets the entire screen to the current 
background color. CLEAR also sets the graphics cursor at 
coordinates 0,0, the lower left corner of the screen. 

Parameters: 
color A code indicating the color to set the screen. 

Examples: 

RUN GFXC™"CLEAR") 
RUN GFAC™CLEAR™, 1429 
om 
o™ 
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COLOR Change the foreground color 


Syntax: RUN GFX(“COLOR’”,color) 


Function: Changes the foreground color (and possibly the color 
set). COLOR does not change the graphics format or the cur- 
sor position. 


Parameters: 
color A code indicating the color you want for the 
foreground. See the chart earlier in this chap- 
ter for color information. 
Examples: 


RUN GPAC™’COLOK”™, 1202 


Sample Program: 


This procedure connects a series of differently colored circles to 
produce a necklace effect. 


PROCEDURE necklace 

OBIS COLOR; TatlsJd.,8,FLAG.ACOR, YCOR: INTEGER 
RUN. GEFXAC "MODE ..7.82 

DORUN GFXC™CLEAR") 

(iCOLOR=1 
UXCOR=1 

UYCOR=1 

UR=2 

FOR T#1 TO & 
(FOR J=1 TO 48 
UXCOR=XCOR+1 
HYCOR=YCOR+.8 
OIF FLAG<@ THEN 
UR=R-1 

HE LSE 

UR=R+1 

LIENDIF 

UCOLOR=COLOR+1 

OIF COLOR>3 THEN COLOR=1 
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fr NEXT J 
NEXT T 
OFOR U=1 
NEXT U 
TEND 


LFLAG=FLAG*- 1 


TO 10080 
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ORUN GFXC™ CIRCLE”, XCOR,YCOR;R,COLOR)D 
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GLOC Find the graphics screen location 


Syntax: RUN GFX(“GLOC”,storage) 


Function: Determines the location of the graphics screen in 
memory and returns the address in the specified variable. 
When you know the graphic screen address, you can use 
PEEK and POKE to perform special functions not available in 
the GFX module, such as filling a portion of the screen with a 
color or saving a graphics screen to disk. 


OS-9 Level Two maps display screens into a program’s 
address space before PEEK and POKE can operate on a dis- 
play screen. This means that you must have at least eight 
kilobytes of free memory in the user’s address space. Program 
and data memory requirements must not exceed 56 kilobytes. 


Parameters: 
storage An integer or byte type variable in which 
GLOC stores the memory address of the 
graphics screen. 
Examples: 


RUN GFXC"GLOC", location) 


Sample Program: 


This procedure uses the GLOC function to locate the current 
graphics screen, then uses POKE to paint a series of boxes on 
the screen. 


PROCEDURE boxin 

UJDIM LOCATION,PLACE,COLOR,BEGIN,QUIT,X,TERMINATE, 
GLNE gl aved ht EGER 

HRUN: GEAC™ MODE 45.09 

URUN GFXCPCLEAR™) 

URUN GFXC"GLOC™,LOCATION) 

JLOCATION=LOCATION+10@ \ PLACE=LOCATION 

UBEGIN=1 

JQUIT=88 
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UCOLOR=255 
UTERMINATE=16 

ULINE=32 

UFOR X=#1 TO 4 

UFOR T=1 TO QUIT 

OUFOR J=BEGIN TO TERMINATE 
UPOKE PLACE+J,COLOR 
UNEXT J 
UPLACE=PLACE+LINE 
NEAT 1 
ULOCATIOQN=LOCATION+160 
UBEGIN=BEGIN+1 
LUIPLACE=LOCATION 
HQUIT=QUIT-18 
UTERMINATE=TERMINATE-1 
UCOLOR=COLOR-85 

UNEXT xX 

UINPUT 2$ 

UEND 
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oJ OYSTK Get joystick status 


Syntax: RUN GFX(“JOYSTK”, stick, fire,xcor,ycor) 


Function: Determines the status of the specified joystick fire 
button and the X,Y position of the specified joystick handle. 
Use this function only with a standard joystick or mouse, not 
with the high-resolution mouse adapter. 


Parameters: 


stick 


fire 


xcor,ycor 


Examples: 


The joystick (0 or 1) for which you want to 
determine the status. 0 indicates the right joy- 
stick, 1 indicates the left joystick. 


A variable in which JOYSTK returns the sta- 
tus of the specified fire button. Fire can be 
byte, integer, or Boolean type. A value other 
than 0 or TRUE indicates the button is 
pressed. 


Byte or integer type variables in which 
JOYSTK stores the X- and Y-coordinates of 
the joystick handle position. The coordinate 
range is 0-63. 


RUN GFXC™JOYSTK",@,shoot,x,y) 


c~ 
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Sample Program: 


This procedure uses the JOYSTK function to draw on the screen 
with the right joystick. 


PROCEDURE joydraw 

DIM STICK,FIRE.xXCOR. YCOR,XTEMPs YTEMPSINTECER 
URUN GFAC@MEDE™. 8,12 

UIRUN GPAC’? CLEAR) 

UJOY=@ \XCOR=@ \YCOR=9@ 

HREPEAT 

UXTEMP=XCOR 

LIYTEMP=YCOR 

URUN: OF Se" JOY STR, 8. FIRE. ACUR.VCUR) 
UXCOR=XCOR*4 

LIYCOR=YCOR*4 

URGN <GPAC™LINE™  XTEMP YTEMP.. XCOR,YCORD 
UNTIL FIRE<>@ 


UEND 
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LINE Draw a line 


Syntax: RUN GFX(“LINE”[,xcorl1,ycor!],xcor2,ycor2 
[,color]) 


Function: Draws a line in the current or specified foreground 
color in one of the following ways: 


e From the current draw position to the specified X,Y- 
coordinates. 


@ From the specified beginning X- and Y-coordinates to the 
specified ending X, Y-coordinates. 
Parameters: 
xcor1 ,ycor1 Are LINE’s beginning X- and Y-coordinates. 
xcor2 ,ycor2 Are LINE’s ending X- and Y-coordinates. 


color A code indicating the color you want the line 
to be. See the chart earlier in this section for 
color information. 
Examples: 
RUM GF AC ’LINE™. 19237289 
RUN GEXC"LINE™.8,590,192,128) 


RUN - GPxXCMLING 0.0, 1923 126,29 
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Sample Program: 


This procedure draws a sine wave of vertical lines across the 
screen. 


PROCEDURE waves 

UDIM A.B C.D yAs¥ sZt NTEGER 
LICALC=@ \ A=100 

RUN GFXC"mode",@,1) 
RUN GFXC™CLEAR™) 

RUNGE. C'COLOR™ 22 

FOR A2S0 TO 255 STEP 7 
LICALC=CALC+.@5 
LIY=A-SINCCALC)*15 
UZ=Y+25 

IR UNESP CY TNE Xe oh eee 
LINEAL: x 

LIEND 
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MODE Switch to graphics screen 


Syntax: RUN GFX(“MODE”,format,color) 


Function: Switches the screen from alphanumeric (text) to 
graphics, selecting the screen format and color code. You must 
run MODE before you can use any other graphics function. 
When you do, BASICO9 allocates a six-kilobyte block of mem- 
ory for graphics. If your system does not have this amount of 
memory available, OS-9 returns an error message. 


Parameters: 
format Either 0 (a two-color 256 by 192 pixel screen) 
or 1 (a four-color, 128 by 192 pixel screen). 
color A code indicating the color to set the screen. 
See the chart earlier in this chapter for infor- 
mation on color sets. 
Examples: 


RUN GFXC"MODE™,1,2) 


9-26 


Displaying Text and Graphics / 9 


MOVE Move graphics cursor 


Syntax: RUN GFX(“MOVE”,xcor,ycor) 


Function: Moves the invisible graphics cursor to the specified 
location on the screen. MOVE does not change the display in 
any way. 


Parameters: 


xcor,ycor The coordinates for the cursor. 


Examples: 


RUN GFAC™MDOVE™, 192,128) 


Sample Program: 


This procedure draws and pops bubbles on the screen using the 
CIRCLE function. It uses MOVE to select the position for the 
circles. 


PROCEDURE bubbles 

DIM XCOR; YCOR,T,R,ARRAYC3,1083:INTEGER 
UIRUN: GFX ™MODE™ 1 58 

URUN GFXC"CLEAR") 

POR Pet Te 28 

DARRAYC1,T)=RNDC255) 
JARRAYC2,T)I=RNDC192) 
UARRAYC3,T)=RNDCSG) 

URUN GFXC™MOVE",ARRAYC1,T)I,ARRAYC2,T)) 
URUN GEXAC"CIRCLE™. ARRAY CS, 1343) 

LINEA TE 

UFOR T=1 TO 20 

URUN GFXC™MOVE",ARRAYC1,T),ARRAYC2,T)) 
URUN GFXC™"CIRCLE",ARRAYC3,T),9) 

HSHELL. "“DESPLAY a7" 

UNEXT T 

END 
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POINT Set point to specified color 


Syntax: RUN GFX(“POINT”,xcor,ycor[,color]) 


Function: Displays a dot at the specified coordinates. If you 
specify a color, POINT sets the pixel at the new coordinates to 
that color. Otherwise, POINT sets the pixel at the new coordi- 
nates to the foreground color. 


Parameters: 
xcor,ycor The X- and Y-coordinates for a pixel. 
color The code of the color you want the pixel to be. 
See the chart earlier in this section for color 
information. 
Examples: 


RUM. GEeachPOInT 132.1282 
RUN GFAC™POINI™, 1925128 ,2) 


Sample Program: 
This procedure uses POINT to draw filled boxes on the screen. 


PROCEDURE boxup 

UIDIM XCOR,YCOR,BEGIN,COLOR,QUIT,TERMINATE,LINE: 
INTEGER 

DIM TaXsVYEINTEGER 

UXCOR=58 \YCOR=308 \COLOR=1 

UBEGIN=1 \START=1 \QUIT=28 \TERMINATE=590 
LIRUN GFXC"MODE™. 1499 

RUN -GFKC™CLEAR™? 

UFOR T=1 TO 4 

(IFOR X=BEGIN TO QUIT 

IIFOR Y=START TO TERMINATE 

UIRUN- GFRCPOINT™, *COR+Y.YCOR,COLGR) 
NEXT -¥ 

LIYCOR=YCOR+1 

NEXT X 

USTART=START+19@ 
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UTERMINATE=TERMINATE-18 
UCOLOR=COLOR+1 

UNEXT EF 

UINPUT 2$ 

END 
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QUIT Deallocate graphics screen 


Syntax: RUN GFX(“QUIT”) 


Function: Switches the screen to the alphanumeric (text) mode 
and deallocates graphics memory. 


Parameters: None 


Examples: 


RUN GFXC™QUIT") 
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High-Resolution Graphics 


BASIC09’s high-resolution graphics greatly expand the capabili- 
ties of the Color Computer 3. You can have greater screen resolu- 
tion (up to 640 by 192 pixels), as many as 64 colors, and the 
ability to mix graphics and text on one screen. In addition, you 
can use different text fonts, or styles. 


The high-resolution module, GFX2, has many more functions 
than its medium resolution counterpart. GFX2 gives you the 
ability to: 


® Select from 64 colors. OS-9 provides a palette with 16 
default colors. You can change any of these default colors to 
any of the 64 colors available on the Color Computer 3. 


@ Set border colors. 

@ Set color patterns. 

® Create different types of graphics screen cursors. 
@ Use logic functions. 

e Turn an automatic scaling function off or on. 

@ Draw outline or filled boxes. 

@ Draw ellipses and arcs. 

@ Fill specified areas with specified colors. 

@ GET and PUT sections of the graphics screen. 


@ Select character fonts, which include boldfaced, transparent, 
and proportionally spaced characters. 


@ Move the cursor. Erase portions of a line or of the screen. 
@ Select reverse or normal video. 
@ Underline text. 


Also, high-resolution graphics operate through the OS-9 Win- 
dowing System. This means that you can run several procedures 
in different windows. You can establish windows to display text, 
or to display graphics, or both. You can easily display any 
window. 
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Establishing a Hardware Window 


For your convenience, OS-9 has a number of predefined or hard- 
ware window formats. Hardware windows are text windows, and 
you cannot use them for graphic applications. Because hardware 
windows are predefined, you can easily establish them with the 
INIZ command. For instance, to establish Window 7, type: 


iniz w/|ENTER 


However, you cannot see the window until you send a message to 
it. Type: 


echo Hello Window 7 > /w7 [ENTER] 


Now, to see the window and your message press (CLEAR). To 
return to the original screen, press (CLEAR) again. 


To OS-9, a window is a device and you can send data to it. To 
view the Errmsg file in the SYS directory of your system 
diskette, list it to Window 7 by typing: 


list sys/errmsg > /w7 (ENTER] 


Press (CLEAR] to move to Window 7 and see the listing. Press 
SHIFT |(CLEAR] to return to the previous screen. 


You can also fork a shell (an execution environment) to a win- 
dow. To cause a shell to operate in Window 7, type: 


shell i=/w7é 


The i= function of SHELL tells OS-9 that the window is im- 
mortal. It does not die after completing a task. To operate OS-9 
from the window, press (CLEAR }. 


Besides Window 7, you have six other predefined windows. The 
following chart shows all the hardware windows and their 
parameters: 
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Starting 

Coordinates 
oa’ Window Screen Size X-Coord, Window Size 
Number Chars/line Y-Coord Cols Rows 
1 40 0,0 27 11 
2 40 28,0 12 jig 
3 40 0,12 40 12 
4 80 0,0 60 Li 
5 80 60,0 19 i 
6 80 0,13 80 12 
7 


80 0,0 80 24 


Defining Windows 


As well as hardware windows, OS-9 also lets you establish win- 
dows to your own specifications. You can set definable windows 
for either text or graphics, or both. You can locate them any- 
where on a screen, and you can make them any size. 


You initialize definable windows in the same manner you initial- 
@) ize hardware windows, using INIZ. If you want to have text on 
the window, you must merge SYS/Stdfonts (found on your system 
diskette) with the window. You can also establish a shell in a 
definable window, from which you can use OS-9 or BASICO9. 


To establish definable windows you must supply OS-9 with infor- 
mation about the type of window you want (its graphic format), 
its size, and its location on the screen. The easiest way to do this 
is with the OS-9 WCREATE command. 
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WCREATE requires a window format code in the form 
- s=format code to tell OS-9 what type of a window you want. 
The following chart shows the possible window formats you can 
choose: 


Table 9.6 
Format Screen Size Resolution No. of | Memory Screen 
Code Cols x Rows Width/Height Colors Required Type 

01 40 x 24 —_—— 167 1600 Text 
02 80 x 24 167 4000 Text 
05 80 x 24 640 x 192 2 16000 Graphics 
06 40 x 24 320 x 192 4 16000 Graphics 
07 80 x 24 640 x 192 4 32000 Graphics 
08 40 x 24 320 x 192 16 32000 Graphics 


00* Specifies the current screen. 
FF Current display screen. Use when putting several windows on the same 
physical screen. 


+ You have to reconfigure the palette to get 16 colors rather than the default of 
eight colors. The following section provides information on the palette. 


Format Codes 01 and 02 select text screens, and Format Codes 5- 
8 select graphics screens. The Screen Size column shows the 
maximum number of text columns and rows available for each 
screen. The Resolution column shows the maximum pixels 
(graphic units) available for each of the graphic screens. The 
Memory column shows how much memory OS-9 must set aside 
for each screen format. Memory requirements depend on the res- 
olution and number of colors selected for a window. 


The Palette 


BASICO9 has 64 colors you can select for screen displays. The 
colors are available through a palette. The Color Computer’s pal- 
ette can hold 16 colors at once. 


9-34 


Displaying Text and Graphics / 9 


The following chart shows the default colors for the palette in 
Screen Format 7: 


Table 9.7 

Register Color Register Color 
00 Black Black 
01 Red 09 Green 
02 Green 10 Black 
03 Yellow 11 Buff 
04 Blue 12 Black 
05 Magenta 13 Green 
06 Cyan Black 
07 White Orange 


Instead of the default colors, you can select any of the 64 colors 
(0-63) for any of the palette registers. You do this using the PAL- 
ETTE command described later in this chapter. The BORDER 
and COLOR commands also affect the colors available in the pal- 
ette by changing the color in the background and foreground 
registers, Registers 02 and 03, respectively. 


Note: The information in the next section assumes you have 
a Color Computer 3 with 512 kilobytes of memory. If your 
computer has 128 kilobytes of memory, skip to the section 
“High-Level Graphics With 128K.” 


Establishing a Graphics Window 


To create any window, you should first initialize it with the INIZ 
command. Type: 


iniz wl [ENTER | 


So that you can later type in the new window, merge the 
Stdfonts file with it. Type: 


merge sys/stdfonts>/wit 


Using the information in the preceding tables, use WCREATE to 
establish a graphics window. The following command line creates 
a graphics window in Window 1 that has 320 x 192 resolution 
and that fills the entire screen. The new window has 16 colors 
available and provides 40 column by 24 line text: 
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wcreate /w1 -5=8 00 00 40 24 03 02 B2 


ae The screen border color 

| The screen background 
color 
The screen foreground 
color 
The screen length in 
rows 
The screen width in 
columns 
The Y-Coordinate for the 
beginning of the screen 
The X-coordinate for the 
beginning of the screen 
The screen type 
The window name 
The command name 


Starting a Shell in a Window 


At this point, the new window exists, and you can send data to 
it. However, if you want to operate from the window, you must 
install a shell in it. Type: 


shell i=/w1& 
Press to move to the new window. To load BASICO9Y, type: 


basicd9 #10K 


Select either more or less memory, according to your needs. 
Using BASICO9 in a graphics window, you can write procedures 
to create high-resolution graphics, and you can display the 
graphics on the same screen. 
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Using High-Level Graphics With 128K 


If your computer is equipped with only 128 kilobytes of memory, 
you cannot use more than one window with BASICO9. Also, to 
use even one window, you must follow certain steps to provide 
enough memory for BASICO9 operations. 


Refer to Table 9.6. You must select a window mode that does not 
use more than 16000 byte of memory—either window Format 5 
or Format 6. 


To provide enough memory to use BASICO9, you must fork a 
shell to the window you create, then kill the shell in TERM. 
Doing this means that you can no longer operate from your 
TERM screen. However, you can run OS-9 and BASICO9 from 
the window. 


The following steps show you how to create a Format 6 graphics 
screen in Window 1, write a BASICO9 high-resolution graphics 
procedure, and execute it using minimum memory. 


1. Boot OS-9. Then, create a graphics window by typing: 
iniz wt (ENTER] 


wcreate /wi -s=06 00 00 40 24 G6 O1 O1 
merge sys/stdfonts>/w' 

shell i=/w1& [ENTER] 

ex (ENTER) 


2. The system stops, and you can no longer type or issue com- 
mands. Press to move to the new window. Then, load 
BASICO9 by typing: 


basic@9Q [ENTER] 
3. Enter the edit mode, and type the following procedure: 


PROCEDURE squeeze 

UDIM XCOR,YCOR,X,Y: INTEGER; RESPONSE:STRING[1] 
URUN GFX@C"CUROFF'') 

JIXCOR=320 \ YCOR=95 \ X=300 \ FLAG=1 
UPRINT CHRS$C12) 

(LOOP 

UFOR Y=1 TO 198 STEP 2 

UX=X-3 

(IGOSUB 1@ 

LITF FLAG<1 THEN 

IRN: GEX2C" COLOR" .09 
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HELSE 
LIRUN: GF X2C"*COLOR™., 3) 

UENDIF 

IRUN GEXCC™ELLIPSE™, XCOR, YCOR.,% 5 ¥2 
LFLAG=FLAG«-1 

UNEXT -¥ 

RUN GF xet" Color™. 1) 

UIFOR Y¥=99 TG 1 STEP -2 

UGOSUB 18 


UX=X+3 
RUN GF RX2C™ELLIPSE™*,XCOR, YCOR.X%,¥ 
UNEXT Y 

JIRUN. GFxec’ COLOR” .8) 

UENDLOOP 

19@URUN INKEYCRESPONSE) 

LIF KRESPONSES"" TREN 

URETURN 

UENDIF 

19UPRINT CHR$ C12) 

UIRUN GFX2C"COLOR", 6) 

URUN GFX2C"CURON'") 


UEND 


When you have entered the procedure exactly as shown, exit 
the edit mode, and from the BASICO9 command mode, save 
Squeeze by typing: 

Save squeeze 
Compile Squeeze by typing: 

pack squeeze 


Squeeze is now an executable module saved in your current 
execution directory. The following steps assume your execu- 
tion directory is /D0/CMDS. 


Exit BASICO9 by typing: 
bye 


Merge Squeeze, RUNB, INKEY, and GFX2 into one module. 
To do this, type: 


merge /d@/cmds/squeeze /d@/cmds/runb /d@/cmds/ 
inkey gfx2 > /d@/cmds/yawn (ENTER | 


wy 
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8. MERGE does not set the new file Yawn as an executable file. 
Before you execute it, you must make the file executable by 


typing: 
attr /d®@/yawn e pe (ENTER] 


9. To execute Yawn, type: 


yawn (ENTER | 


10. To terminate the procedure, press the space bar. 


The merging procedure in Step 7 saves a considerable amount of 
memory. Every module you load uses one or more 8-kilobyte 
blocks of storage space. For instance, INKEY is only 94 bytes in 
length. However, if you load it as a separate module, it requires 
8192 bytes. RUNB is 12185 bytes in length. This means that it 
requires two 8-kilobyte blocks, or 16384 bytes of memory. GFX2 
is 2190 bytes in length, and Squeeze is 605 bytes in length. 
Loaded individually, they also require two memory blocks. 


If you load all four modules independently, they use 40960 bytes. 
However, by combining them into one file, they load into two 
memory blocks, or 16384 bytes. 


Using the information in this section, you can write and execute 
numerous BASICO9 procedures with only 128 kilobytes of mem- 
ory. However, if your computer has 512 kilobytes of memory, you 
can bypass many of these steps. Also, the additional memory 
enables you to have several windows open at one time. For 
instance, you can create one window in which to write BASICO9 
procedures, another window in which to execute your procedures, 
and a third window from which you can use OS-9 commands. 


Note: The remainder of this chapter assumes you have 512 
kilobytes of memory. If you don’t, you can still run many of 
the sample procedures by implementing the steps in this 
section. 


Creating Windows from BASICO09 


Using GFX2 routines, BASICO9 provides the means to create 
and manage windows. The steps for creating windows from 
BASIC09 are as follows: 


1. DIM a variable to hold the path number to the window you 
want to create. 
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2. OPEN a path to the window. 
3. SELECT the new window as the display window. 


4. Send commands, data, or text to the window through the open 
path. 


5. CLOSE the open path. 
6. Use SELECT to return to your original window. 


If you do not want to return immediately to the screen or win- 
dow of origin, you can skip Steps 5 and 6. 


The following sample procedure shows how to open Window 2 as 
a 320 x 192 graphics window, draw a circle, then return to the 
original screen when you press a key. 


PROCEDURE make__win 

DIM PATH: INTEGER 

DIM RESPENSEsSTERINGL 1 2 

OPEN #PATH,"/We": WRITE 

RUN GFX2 CPATH,"DWSET",08,00,00,40,24,03,02,02) 
RUN GFkS CPATH. "SELECT"? 

RUN GFxS CPATH. “CIRCLE”, 208,98 ,89> 
GET #1.,RESPONSE 

CLOSE #PATH 

RUN GPa. O'SELECT) 

END 


This procedure establishes a Format 8 window, beginning at 
Coordinates 0,0 and covering the total screen. The foreground 
color is green, the background color is black, and the border color 
is black. 


Because this procedure does not INIZ the window it opens, the 
window automatically disappears when the procedure closes its 
path. To create a window that stays in the system, even after 
you close the path to it, use INIZ before the OPEN statement, 
like this: 


SHEGL. “iN swe" 


After you create and define the window, view it by pressing 
(CLEAR }. To get back to the screen you are working on, press 
(CLEAR }. If you intend to use a window more than once in a proce- 
dure, you do not need to close its path until the procedure no 
longer needs it. 
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Creating Overlay Windows 


When you establish a window, you are initializing an OS-9 
device. However, an overlay window is only a new screen for an 
existing window. An overlay screen can be the same size as its 
window, or it can be smaller. OS-9 automatically transfers to the 
overlay window any current procedures operating in the device 
window. 


The process for creating overlay windows lets you select whether 
you want to save the contents of the screen covered by the new 
window. If you choose to save the contents, the previous screen is 
redisplayed when you end the overlay. 


The following procedure provides an example of using overlay 
windows. It creates six overlays, each smaller than the preceding 
window. The procedure then waits for you to press a key. When 
you do, it removes the overlay windows. 


PROCEDURE overwindows 

HDI Aav¥oR lay 1 led Belk PLACE s INTEGER 
UDIM. RESPONSE sSTRINGI 1) 

(X=8 \Y=@ 

“X1=8@ \Y1=24 

UIPLACE=33 

UFOR T=1 TO 6 

HIF T=2 OR T=6 THEN 

JB=3 

VELSE Bee 

BEND LE 

ROS: GF eC OSE Td oh vay ee hg Vo ey 1 
[IX=X+G6 \Y=Yr2 

UX1=X1-12 \Y1=Y1-4 

UFOR J=1 TO 5 

LIPRINT TABCPLACE); “VER ay Se hmem, 23, oF 
NEXT J 

UPLACE=PLACE-6 

i ee ae 

JPRINT “Overlay Screen 6" 

LPRINT “PreSs fi Keys oa" 4 

UIGET #1,RESPONSE 

FOR T=1 TO 6&6 

“RUN GFX2@C"QWEND") 

NEAT OT 

WIEND 
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The Graphics Cursor and the 
Draw Pointer 


High-resolution graphics provide a text cursor, a graphics cursor, 
and a draw pointer. The text cursor and the graphics cursor can 
be either visible or invisible. The draw pointer is always 
invisible. 


Text functions always begin at the current location of the text 
cursor. Whenever you print on the screen, the cursor automati- 
cally moves to the end of the text or to the beginning of the next 
line, depending on whether or not you use a semicolon after the 
print statement. You can reset the text cursor to any place on 
the screen with the CURXY function of GFX2. 


Many BASICO9 graphics functions also begin operating at a 
location pointed to by the draw pointer. When you begin graph- 
ics, the draw pointer is located at coordinates 0,0. BASICO9 then 
updates the pointer as you execute certain graphics functions. 
For instance, the LINE function of GFX2 draws from the draw 
pointer position to the specified end coordinates. The draw 
pointer is left pointing to the end coordinates. 


Because some functions begin at the draw pointer, you need to 
keep track of its location and make certain it is placed properly. 
Use the SETDPTR function to move the draw pointer to new 
locations. 


The graphics cursor is for use with joystick or mouse operations. 
It provides a pointer for graphics applications. The system 
diskette provides patterns that can be loaded into the graphics 
cursor buffer. You can select from a variety of pointer images. 


High-Resolution Text 


When you create a graphics window, you can display either text 
characters, graphics characters, or both. 


To display graphics, move the draw pointer to the location where 
you want the graphics to begin. Then, execute the graphics 
routines. 


To display text, move the text cursor to the location where you 
want the text to begin. Then, use normal BASIC commands to 
print text. 
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Instructions for the draw pointer relate to a 640 x 192 grid, 
numbered 0-639 and 0-191. Instructions for the text cursor 
relate to the number of characters per line and the number of 
lines on the current screen format. 


Using Fonts 


OS-9 has built-in fonts (character sets). You can also create your 
own fonts and instruct BASICO9 to use them. If you create your 
own fonts, you can design any symbols or graphics characters 
you want to use. 


To use fonts, you must be in a graphics window. See “Establish- 
ing a Graphics Screen” earlier in this chapter. Use the FONT 
function to tell OS-9 what font you want. BASICO9 has three 
fonts installed in Group 200, Buffers 1, 2, and 3. The following 
procedure uses characters in Buffer 3 to draw a border, then 
prints a message using the characters in Buffer 2. It then 
returns to Buffer 3 and asks you to press a key to end the 
procedure. 


PROCEDURE borders 

HBiM T2483 Vs0,K2 INTEGER 
UDIM RESPONSE:STRINGL1 1 
UB=199 

UPRINT CHRS$€12) 

LIRUN: GF X!SC™F ONT, 20¢0,3) 
UIRON GF X2C"CELGR”.1 523 
UFOR T=@ TO 79 

UPRINT CHR$CB); 

ONEXT T 

UFOR T=1 TO 21 

LIRUN: GFASC’CURXY™, 8,172 
PRINT CHRSCB)s CHRS(CB); 
RUN GF ACC ™CURKY™ 78.013 
UPRINT CHR$€B); CHR$CB); 
LINEXT T 

UIRUN. GF Z20"CURXY" 8.27) 
UPGR T=% TG 78 

UIPRINT CHRSCB): 

UNEXT T 

URUN GFk2C"FONT™, 200.2) 
RUN GF A2C™CUOLEGR™, 9,29 
RUN GP X2C"CURXY™ 45.92 
UPRINT "A Demonstration" 
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RUN GFXSC™CURXY™ 508.10) 
PRINT “OF A" 

ORUN GFXSC™CURXY™ 43.11) 
UPRINT “Buffer Three Border" 
CRUE “GF KEC™CURKY"™ 51.4 729 
PRINT “And 

PIREEN:- GEX2CeCURKY™, 45.173) 
UPRINT “Buffer Two Text" 
ORUN GFX2C"FONT",200,1) 
DRUN GFX2C"COLOR™ 352) 
LRUN: GFXEC™CURXY™. 33.175) 
UPRINT “Press A Keyes. 0?" 
OGET #1,RESPONSE 

UPRINT CARS C122 


UEND 


High-Resolution Quick Reference 


High-resolution functions are all part of the GFX2 module. You 
call them in a BASICO9 procedure with the following syntax: 


RUN GF ASCI PATA se“ FUNCTION’C PARAMETER, <>) 19 


Path is an optional variable name that tells OS-9 the window in 
which you want the function performed. Function is the high- 
resolution task you want to perform. Parameter is an essential or 
optional value that affects the performance of the function. Dif- 
ferent functions require or permit different numbers of 
parameters. 


The following reference gives a brief description of the high- 
resolution graphics functions. This list is organized by function. 
Following the quick reference is a detailed reference organized 
alphabetically. 
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Window Commands 


Command 


DWSet 


OWSet 


OWEnd 
Select 

DWEnd 
CWArea 


DWProtectSw 


Function 


Establishes a window and sets its location 
on the screen, its size, its background color, 
its foreground color, and its border color. 


Establishes an overlay window on a device 
window that already exists. The function 
also sets the overlay window size, back- 
ground color, foreground color, and border 
color. When using this function, you can 
choose whether or not to save the contents 
of the original screen. 


Deallocates the specified overlay window. 
Selects the window to display. 
Deallocates an established window. 


Changes the size of a window. You can only 
reduce the working area of a window, not 
increase it. 


Lets you unprotect a window and set other 
device windows over it. This might destroy 
the contents of either or both windows. 
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Drawing Commands: 


Command Function 

Point Sets the pixel under the draw pointer to the 
specified color or to the default color. 

Line Draws a line. 

Box Draws a rectangle outline. 

Bar Draws a filled rectangle. 

Circle Draws a circle. 

Ellipse Draws an ellipse. 

Arc Draws an arc. 

Fill Fills the area of the window the same color 


as the pixel under the draw pointer. 


Clear Clears the window. 
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Configuring Commands: 


Command 


Color 


DefCol 
Border 
Palette 


Pattern 
Logic 
GCSet 


ScaleSw 
SetDPtr 
PutGC 


Draw 


Function 


Sets any of the foreground, background, or 
border colors. 


Sets palette registers to the default colors. 
Sets the border palette register. 
Changes colors in the palette registers. 


Establishes a buffer from which BASICO9 
gets a pattern for graphics functions. 


Turns on AND, OR, or XOR logic functions 
for draw functions. 


Establishes a buffer from which BASICO09 
gets the graphics cursor. 


Turns scaling on or off. 
Positions the draw pointer. 
Positions the graphics cursor. 


Draws an image from directions provided in 
a draw string. 


Get/Put Commands: 


Command 


Get 


Put 


DefBuff 
GPLoad 
KillBuff 


Function 


Saves a specified portion of a window to a 
buffer. 


Places the image stored in a buffer onto a 
window. 


Defines a buffer for storage. 
Preloads a buffer from a disk file. 


Deallocates a buffer. 
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Text/Cursor Handling Routines: 


Command Function 

CurHome Positions the cursor at coordinates 0,0. 

CurXY Positions the cursor at_ specified 
coordinates. 

ErLine Erases the line under the cursor. 

ErEOLine Erases from the cursor to the end of the 
line. 

CurOff Turns the graphics cursor off. 

CurOn Turns the graphics cursor on. 

CurRgt Moves the graphics cursor right one space. 

Bell Sounds the terminal bell. 

CurLft Moves the graphics cursor left one space. 

CurUp Moves the graphics cursor up one line. 

CurDwn Moves the graphics cursor down one line. 


9-48 


Displaying Text and Graphics / 9 


Font Handling Commands: 


Command 


Font 


TCharSw 
BoldSw 
PropSw 
ErEoWndw 


Clear 
CrRtn 


ReVOn 
ReVOff 
UndInOn 
UndInOff 
BlnkOn 


BinkOff 


InsLin 


DelLin 


Function 


Specifies the buffer from which BASICO9 
selects its font characters. 


Selects or deselects transparent characters. 
Selects or deselects bold characters. 
Selects or deselects proportional characters. 


Erases from the graphics cursor to the end 
of the window. 


Erases window and homes the cursor. 


Performs a carriage return by moving the 
cursor down one line and to the extreme left 
of the window. 


Turns reverse video on. 
Turns reverse video off. 
Turns the underline function on. 
Turns the underline function off. 


Turns blinking characters on (only for hard- 
ware text screens). 


Turns blinking characters off (only for hard- 
ware text screens). 


Inserts a blank line at the graphics cursor 
position. 


Deletes the line at the graphics cursor 
position. 
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ARC Draw an arc 


Syntax: RUN GFX2([path,|“ARC”[,mx,my], 
xrad, yrad,xcor1,ycor1,xcor2, ycor2) 


Function: Draws an arc at the current or specified draw posi- 
tion with the specified X and Y radius. If you specify the 
same radius for both X and Y, the function draws a circular 
arc, otherwise the arc is elliptical. The X coordinates are in 
the range 0-639. The Y coordinates are in the range 0-191. 


ARC begins drawing from the point on the screen closest to 
the first set of coordinates (xcorl, ycor1). It stops at the por- 
tion of the screen closest to the second set of coordinates 
(xcor2, ycor2). You can determine on which side of the line 
ARC draws by selecting which set of coordinates is the begin- 
ning and which set is the end. 


Parameters: 


path 
mx,my 
xrad 


yrad 


xcorl ,ycor1 
xcor2 ,ycor2 


Examples: 


The route to the window in which you want to 


draw an arc. 


The X- and Y-coordinates for the center of the 
arc. If you do not specify mx and my, BASICO9 
uses the current draw pointer position. 


The radius of the arc’s width. 
The radius of the arc’s height. 


The beginning and ending coordinates for an 
imaginary line from which the function draws 
an arc. The line is relative to the center of the 
arc (the center point is at 0,0 for these coordi- 
nates) and extends through the two coordi- 
nates from one edge of the screen to the other. 


RUN GFX2C"ARC™, 58,168,509 ,100,30,7598) 
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Sample Program: 


a This procedure draws a series of diagonally-cut arcs on a graph- 
ics window screen. 


PROCEDURE arcing 

ODIM MX,MY,XRAD,YRAD,XCOR,YCOR,XCOR2,YCOR2: INTEGER 
DIM Taoka¥ 22 INTEGER 

UIPRINT CHR$C€12) 

UPOR TS 1a Qe STEP 2 

RUN GFX2C™ARC™.318,95.,1750,159351<9 
LIRUN -GFX2C™ARC’ ,324,95.158,1,1,4851 
LINEXT T 


me 
1) 


? 
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BAR Fill a rectangle 


Syntax: RUN GFX2((path,|“BAR”[,xcorl1, ycor!1],xcor2, 
ycor2) 


Function: Fills a rectangular area defined by two sets of coor- 
dinates. BAR defines its area with an imaginary diagonal 
line from the first set of coordinates to the second set of coor- 
dinates. The X coordinates are in the range 0-639. The Y 
coordinates are in the range 0-191. 


Parameters: 
path The route to the window in which you want to 
draw a bar. 
xcor1 ,ycor1 The beginning coordinates of the line defining 


the area to fill. If you omit these coordinates, 
BAR uses the draw pointer position. See the 
previous section “The Graphics Cursor and 
The Draw Pointer.” Also see SETDPTR. 


xcor2,ycor2 The ending coordinates of the line defining the 
area to fill. 


Examples: 


RUN GFX2C"BAR", 208,100) 


RUN GFX2C"BAR",08,09,100,50) 


Sample Program: 
This procedure draws a bar chart on a window screen. 


PROCEDURE OSgraf 

UDIM COLOR,T,X,XCOR1,YCOR1,XCOR2,YCOR2: 

INTEGERS RESPONSE STRING 11 

LUIPRINT CHR$C€12) 

RUN GFX2C"DEFCOL™) 

-COLOR=13 \ XCOR1=1@ \ YCOR1=189 

JXCOR2=XCOR1+40 

UIRUN GFX2C™"CUROFF"') 
mcmama 
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UFOR T=1 TO 19 

UJREAD YCOR2 

UIRUN GFX2@Cc"COLOR",COLOR) 

URUN GFX2C"BAR", XCOR1,YCOR1,XCOR2,YCOR2) 
UIRUN GF X2c™"COLOGR",7) 

URUN -GEX2C"BOX*, XCOR1 .YCORT,XCOR]. YCORZ) 
JICOLOR=COLOR+1 \ XCOR1=XCOR1+5@ \ XCOR2=XCOR1+49 
NEAT oF 

Peon? \. PRINT © OS-9 Sales Chart" 
URUN GFX2c"BOX",8@,0,510,180) 

UGET #1,RESPONSE 

LIRUN GFX2@C™CURON') 

UPRINT CHR$(12) 

CEND 

-DATA 1780,158,140,130,110,90,70,60,50,39 
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BE LL Ring the terminal bell 


Syntax: RUN GFX2(“BELL”) 


Function: Rings the terminal’s bell (produces a beep through 
the speaker). 


Parameters: None 


Examples: 


RUN: GF X2C"BELL™) 
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BLN KON Character blink on 
BLN KOF F Character blink off 


Syntax: RUN GFX2([path,|“BLNKON’’) 
RUN GFX2([path,]|““BLNKOFF’’) 


Function: Executing BLNKON causes all subsequent charac- 
ters sent to a window on a hardware screen to blink. A hard- 
ware screen is one of the predefined device windows /W1 
through /W7. Executing BLNKOFF cancels a previous blink 
command; characters already blinking continue to do so. Blink 
does not operate on graphics windows. 


Parameters: 
path The route to the window in which you want to 
blink characters. 
Examples: 


RUN GFXeC™BLNKON' 2 


RUN GF ASCVBLNKOPE™) 
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BOLDSW Switch bold characters on or off 


Syntax: RUN GFX2([path,]“BOLDSW”,“switch’) 


Function: Causes characters to display in either regular or 
bold typeface. The default is regular typeface. BOLD only 
works on graphics screens. 


Parameters: 
path The route to the window in which you want 
bold characters. 
switch Can be either “ON” or “OFF.” If switch is 
“ON,” subsequent characters are bold. If 
switch is “OFF,” subsequent characters are 
not bold. 
Examples: 


RUN Grice BELDSHY.“ON"™) 


Sample Program: 


This procedure demonstrates the BOLDSW function by display- 
ing both bold and normal text on a window screen. 


PROCEDURE bold 

UDIM LINE:STRING 

DIM LETTERSSTRINGLE 13 
UDIM: T,35,FLAG? INTEGER 
URUN GFX2@C"CLEAR") 
UFLAG=1 

UFOR T=1 TO 8 

UREAD LINE 

JFOR J*1 TO LENCLINED 
JLETTER=MIDSCLINE «51 


LHe LETTERS AND LET PERS oe “THEN 
PRINT LETTERS 

UENDIF 

Er LETTERS "Sf" oFoeEN 


LIFLAG=FLAGs-1 


ee SE ET SE a A SR SS PT SSE 


9-56 


Displaying Text and Graphics / 9 


HIF FLAG>@ THEN 

LWIRUN GFXSC"BOLDSWY."OFF*)> 

ELSE 

RUN GFX2eCc"BOLDSW","ON'') 

OENDIF 

ENDIF 

DIF LETTER=""#" THEN 

UPRINT CHR$C€34):; 

UENDIF 

NEXT al 

OPRINT 

ONEXT T 

DOPRINT \ PRINT 

DEND 

UDATA "This is a demonstration of" 
JIDATA "the !Bold! function of" 
UDATA "BASIC09’s GFX2 module." 
UDATA "Use the command" 

UDATA "!RUN GFX2C#BOLDSW4,#0N#)!" 
UDATA "to turn boldface on." 
UDATA "Use !RUN GFX2C#BOLDSWe ,#OFFe)I" 
UDATA “to turn boldface off" 
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BORDER Set the border color 


Syntax: RUN GFX2([path,|“BORDER’”,color) 


Function: Resets the palette register that affects a window’s 
border color (Register 0) to the specified color code. For infor- 
mation on the palette and on screen colors, see “The Palette” 
and Table 9.7 earlier in this chapter. 


Parameters: 
path The route to the window in which you want to 
change border color. 
color One of the current palette colors. Color can be 
either a constant or a variable. 
Examples: 


RUN OP X2C" BORDER”, 72 


Sample Program: 


This procedure lets you select different border colors by 
pressing or (—] to select higher or lower color codes. 
Press (q) to end the procedure. 


PROCEDURE border 

DIM COLOR: INTEGER 

UDIM KEY2:STRINGET I 

LICOLOR=8 

UIRUN GFx2C" CLEAR? 

WHILE KEY<9"™q™" AND KEY<2"Q" DO 
OGET #1,KEY 


OIF KEY="-" OR KEY="=" THEN 
OCOLOR=COLOR-1 

JENDIF 

OIF KEY="+" OR KEY="3;" THEN 
OCOLOR=COLOR+1 

OENDIF 
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DIF COLOR>15 QR COLOR<@ THEN COLOR=8 
UENDIF 

URUN GFX2C"BORDER",COLOR) 

ERUN GFEACC™CURXY” 5. 8.583 

UENDWHILE 

HEND 
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BOX Draw a rectangle 


Syntax: RUN GFX2([path,]“BOX”[,xcorl,ycor1], 
xcor2, ycor2) 


Function: Draws a rectangle. BOX defines its area with an 
imaginary diagonal line from the first set of coordinates to 
the second set of coordinates. BOX does not reset the draw 
pointer. The X coordinates are in the range 0-639. The Y 
coordinates are in the range 0-191. 


Parameters: 
path The route to the window in which you want to 
draw a box. 
xcorl,ycor1 The beginning coordinates for the line that 
defines the rectangle to drawn. If you omit 
these coordinates, BOX uses the draw pointer 
position. 
xcor2,cor2 The ending coordinates for the line that 
defines the rectangular area to be drawn. 
Examples: 


RUN GFX2C"BOX", 200,100) 


RUN GFX2C™BOX" .0,0,1089,58) 


Sample Program: 


This procedure draws a series of progressively smaller boxes of 
different colors on a window screen. Then, it rapidly changes the 
colors of the boxes to produce a hypnotic effect. 


PROCEDURE hypbox 

IDEM As Yak to VI el eRe COULGREINTIEGER 
DIM KEY SSTRINGTT I 

Ley eee 

UX=18 \Y=6 

UY1=18S \X1=621 

URUN GFX2C"CLEAR") 


aera rreeree sre s reese cccccccc  S SSSSSSSSSSSSSSSS 
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FOR T=8 TO 1S 

UCOLOR=T 

RUN GFxX2cC"CcoLOR™ ,3) 

UIRUN. GE ASC" BOR 25 95445 12 
URUN GFX2c"COLOR",COLOR) 
RUN: Geeeo Tr TLL cat. yD 
UX=X+18 \Y=Y+G 

UXTSK TTS AY THVT H6 

UNEAT. © 

IWAICE KeEY=""" (DO 

URUN INKEYCKEY) 

UFOR T=1 TO 16 

UR=RNDC65) 

RUN GPxX2C™"PALETTE™,T>R9 
UNEXT T 

UJENDWHILE 

UIRUN: GPX2C™DEFCOL**> 

LEND 
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CIRCLE Draw a circle 


Syntax: RUN GFX2([path,]“CIRCLE”[,xcor,ycor], 
radius) 


Function: Draws a circle with a specified radius. If you specify 
coordinates, CIRCLE uses them for the center point. Other- 
wise, CIRCLE locates the center of the circle at the current 
draw pointer position. See “The Graphics Cursor and the 
Draw Pointer” earlier in this section. Also see SETDPTR. 


Parameters: 
path The route to the window in which you want to 
draw a circle. 
xcor,ycor The coordinates for the circle’s center. The X 
coordinates are in the range 0-639. The Y 
coordinates are in the range 0-191. 
radius The radius of the circle. 
Examples: 


RUN GFX2C"™CIRCLE",100) 


RUN GFX2C"CIRCLE",108,200,50) 
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Sample Program: 
> This procedure uses circles to produce a geometric design. 


PROCEDURE ciraround 
DIM T,45 Ye INTEGER 
LIPRINT CHR$C€12) 

ORUN GP ReEC™COLGR"™, 1.29 
UFOR T=1 TO 130 
UX=158*SINCT)+320 
UY¥=25*COUSCT)+96 

UIRUN: (GF REC™CERCLE™:Xs.¥5 100) 
HNG Aw ob 

URUN GEXSC™COLUR™, 3.2) 

POR T=1 TO 45 
UX=150*SINCT)I+329 
UY¥=25*COSCT)+96 

RUN GFK2CYCIROLE xs YI ee2 
LINE oe 


END 
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CLEAR Clear the screen 


Syntax: RUN GFX2([path,|“CLEAR’’) 


Function: Clears the current working area of a window. 
CLEAR does not change the location of the draw pointer but 
does set the text cursor and graphics cursor location to the 
upper left corner of the window. 


Parameters: 


path The route to the window you want to clear. 


Examples: 


RUN GF X2C"CLEAR™) 
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COLOR Set screen colors 


Syntax: RUN GFX2([path,]“COLOR”, 
foreground|, background], border}) 


Function: Changes any of the foreground, background, or the 
border colors. COLOR does not change the draw pointer 


position. 


Parameters: 


path 
foreground 
background 


border 


Examples: 


The route to the window in which you want to 
change one or more screen or text colors. 


The register number for the foreground 
palette. 


The register number for the background 
palette. 


The register number for the border palette. 
Changing the border color for any window on a 
screen, changes the border color for all win- 
dows on the same screen. 


RUN GFX2C"COLOR",1) 
RUN GAC CULUR™ 1522 
RUM, GF ASCP COLER™ 1,247 2 
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Sample Program: 


This procedure fills a window screen with multicolored filled 
circles. 


PROCEDURE bubbles 

EDIM: X—5¥oW,2,T SiN TeEGeErR 
UZ=1 

DRUM GFA2CVEOCOR’. 1,082 
ORUN GFX2C™"CLEAR") 

UFOR T#=1 TO 88 
UX=RNDC635)+4 
UY=RNDC185)+5 
UW=RNDCS8+5) 

LZ=Z+ 1 

ULF 293 THEN 221 

REND 

RUN GFX2C"CIRCLE™, X,Y ,W) 
RUN GFR2C"COLUR™., 2) 

RUN GPACC VE TEL A 4% 2 


DINE ST TF 
UIRUN -OF Ket" COLOR". 3, 2,22 
END 
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CRRIN Carriage return 


Syntax: RUN GFX2([path,]“CRRTN”) 


Function: Causes BASICO9 to send a carriage return to a 
window. The cursor moves down one line and to the extreme 
left of the window. 


Parameters: 
path The route to the window in which you want a 
carriage return. 
Examples: 


RUN GF F2CVCRETN 2 
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CURDWN Cursor down 


Syntax: RUN GFX2([path,]“CURDWN”’) 


Function: Moves the cursor down one text line. The X-coordi- 
nate, or column position, remains the same. 


Parameters: 
path The route to the window in which you want to 
move the cursor. 
Examples: 


RUN GFX2C"CURDWN") 
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CURHOME Cursor home 


Syntax: RUN GFX2([path,]“CURHOME”’) 


Function: Moves the text cursor to the top left corner of the 


screen. 
Parameters: 
path The route to the window where you want to 
reset the cursor 
Examples: 


RUN GFX2C"CURHOME') 


9-69 


BASICO9 Reference 


CURLFT Move cursor left 


Syntax: RUN GFX2([path,]“CURLFT”’) 


Function: Moves the cursor one character to the left. 


Parameters: 
path The route to the window where you want to 
move the cursor. 
Examples: 


RUN “GF AEC CURLET 2 
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CUROF F Turn off cursor 


Syntax: RUN GFX2([path,]“CUROFF”’) 


Function: Makes the cursor invisible. 


Parameters: 
path The route to the window in which you want to 
turn the cursor off. 
Examples: 


RUN GFX2@C"™CUROFF') 
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CURON Turn on cursor 


Syntax: RUN GFX2([path,]“CURON”) 


Function: Makes the text cursor visible. 


Parameters: 
path The route to the window in which you want to 
turn the cursor on. 
Examples: 


RUN GFX2C"CURON") 
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CURRGT Move cursor right 


Syntax: RUN GFX2(“[path,.|CURRGT”) 


Function: Moves the cursor one character to the right. 


Parameters: 
path The route to the window in which you want to 
move the cursor. 
Examples: 


RUN GFX2C"CURRGT') 
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CURUP Move cursor up 


Syntax: RUN GFX2([path,]“CURUP”) 


Function: Moves the cursor up one line. 


Parameters: 


path The route to the window in which you want to 
move the cursor. 


Examples: 


RUN GFASC™CURUP™ ) 
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CURXY Set cursor position 


Syntax: RUN GFX2([path,|“CURXY”,column,row) 


Function: Moves the cursor to the specified column and row 
position. The column and row coordinates are relative to the 
window’s current character width and depth. 


Parameters: 
path The route to the window in which you want to 
move the cursor. 
column The column (horizontal) position for the 
cursor. 
row The row (vertical) position for the cursor. 
Examples: 


RUN GFX2C™CURXY". 185799 
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CWAREA Change working area 


Syntax: RUN GFX2([path,]“CWAREA”,xcor, ycor,sizex, 
sizey) 


Function: Restricts output in the window to the specified area. 
The new area must be the same or smaller than the previous 
working area. When a window’s working area is changed, 
OS-9 scales graphic and text coordinates and graphic images 
to the new proportions. Text characters remain the same size. 


Parameters: 
path The route to the window in which you want to 
change the working area. 
xcor,ycor The beginning coordinates (the upper left cor- 
ner) for the new working area, relative to the 
original window. The coordinates are based on 
the character column and row size of the origi- 
nal window. 
sizex Designates the number of columns in the new 
working area. 
sizey The number of lines available in the new 
working area. 
Examples: 


RUN GFX2C"CWAREA",180,0,40,10) 
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Sample Program: 


This procedure makes the working area in a window progres- 
sively smaller, filling each area with a different color. It then 
changes the areas’ colors rapidly to produce a hypnotic effect. 


PROCEDURE hypnobox 

UDIM As ¥sX14 715 Fo Rs COLOR: INTEGER 
UDIM KEY:STRINGI11] 

UKEY=""" 

UX=3 \Y=1 

UX1=80-CX+X) \Y1=24-CY+Y) 
FOR T=8 TO 190 

URUN GFX2C’CoLoR™,3,T) 

UIRUN GFX2c™CLEAR") 

UORUN GFX2C"CWAREA™.,X5Y¥sX15V19 
UX=X+3 \Y=Yr1 

UX1=88-CX+X) \Y1=24-CY+Y) 


UNEXT T 
URUN GF xe2C’COULUR™, 3,22 
UWHILE KEY="" DO 


URUN INKEYCKEY) 


UFOR T=1 TO 16 
UR=RNDC65) 

RUN GFX2C™PALETTE™,T RD 
UNEXT T 

UENDWHILE 

RUN GEX2C™DEFCOL**) 


URUN GFX2C"CWAREA",8,8,80,24) 
UEND 
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DE FBUFF Define GET/PUT buffer 


Syntax: RUN GFX2(“DEFBUFF”,group, buffer,size) 


Function: Defines a buffer for GET/PUT operations. 


When you define a buffer, you do so by group number and 
buffer number. Each group you define allocates eight kilobytes 
of memory. The system needs 30 bytes of the block for over- 
head, leaving 8162 bytes free. Within the group, you can allo- 
cate one or more buffers. Select a group number and a buffer 
number as indicated in the following “Parameters” section. 
Use these numbers in future references to the buffer. 


A GET/PUT buffer remains allocated until you use the KILL- 
BUFF function to remove it from your system’s memory. For 
more information on Get/Put buffers, see KILLBUFF, PUT, 
GET, and GPLOAD. 


Parameters: 
group A number you select in the range 1-199. 
buffer A number (in the range 1-255) that you 
assign to the buffer you create. 
size The size of the buffer, in the range of 1 to 
8192 bytes, depending on available memory in 
its group. 
Notes: 


One method of selecting a group number is to use SYSCALL 
and the Get ID (103F OC) system call to obtain your user’s 
process ID number. Then, use this ID number as a group 
number. Using this system for all GET/PUT buffer operations, 
ensures against group number overlapping. See the SYS- 
CALL command for more information. 


Examples: 


RUN GFX2C"™DEFBUFF™,1,5,4809H9) 
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DE FC OL Set default colors 


Syntax: RUN GFX2([path,|“DEFCOL’’) 


Function: Sets the palette registers back to their default val- 
ues. The type of monitor you have determines the actual hues. 
See “The Palette” and Table 9.7 earlier in this section. 


Parameters: 
path The route to the window in which you want to 
restore the original palette registers. 
Examples: 


RUN OF ACC" DEF COL”? 


9-79 


BASIC09 Reference 


DE LLIN Delete current line of text 


Syntax: RUN GFX2([path,]“DELLIN”) 


Function: Deletes the line on which the cursor is resting and 
closes the space. DELLIN operates on both text and graphics 
screens. 


Parameters: 
path The route to the window in which you want to 
delete a line. 
Examples: 


RUN GFxX2C™DELLIN"™D 


Sample Program: 


This procedure draws a series of various colored concentric cir- “” 


cles, then produces a lemon shape by removing slices of the circle 
with DELLIN. 


PROCEDURE slice 

UDIM X,Y,R,T,COLOR: INTEGER 
URUN GFX2C™CLEAR"™) 
UCOLOR=8 

UX=328 

LY=96 

LrOR T=165: 10 18 STEP =19 
RUN GFXSC* CIRCLE". X,Y .7T) 
UNEXT T 

FOR T=148 TO 328 STEP 198 
URUN GFX2C™"COLOR™,COLOR) 
UIRUN GFX2C"FILL™,T,96) 
UCOLOR=COLOR+1 

UNEXT T 

URUN GFX2C™"CURXY",@,8) ww 
UFOR T=1 TO 8 

URUN GFX2@C™DELLIN") 


NEXT. T 
LIRUN GF X2¢"COLGR", 3,2) 
UEND 


ee ee ee ee ee 
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- DRAW Draw a polyline figure 


Syntax: RUN GFX2([path,]“DRAW”, option list) 


Function: Draws in the directions specified, and for the dis- 
tances specified, in an option list. The option list is a string of 
characters and numbers. You can separate options with spaces 
or commas. You must include commas between the two coordi- 
nates for the B and U options. 


Parameters: 
path The route to the window in which you want to 
draw. 
option list A string consisting of one or more of the fol- 
lowing options: 
Options: 
Nnum draws north (up) num units. 
Snum draws south (down) num units. 
Enum draws east (right) num units. 
Wnum draws west (left) num units. 
NEnum draws northeast (up and right) num units. 
NWnum draws northwest (up and left) num units. 
SEnum draws southeast (down and right) num units. 
SWnum draws southwest (down and left) num units. 
Aval rotates the draw axis. Possible values are: 
0 = normal 
1 = 90 degrees 
2 = 180 degrees 
3 = 270 degrees 
Uxcor,ycor draws a relative vector to the specified coordi- 
nates. Xcor and ycor are relative to the cur- 
o- rent draw pointer position. The draw pointer 


location does not change. Xcor and ycor must 
be separated by a comma. 
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Bxcor,ycor produces a blank line (moves the cursor but 
does not draw). The xcor and ycor coordinates 
are relative to the current draw pointer loca- 
tion. If you specify relative coordinates located 
offscreen, you cannot see subsequent lines. 


Examples: 


RUN GFX2C™DRAW","N10,610,510,W10") 
Sample Program: 


PROCEDURE drawing 

ODIM T,X%,¥,COLOR: INTEGER 
UCOLOR=9 

RUN GFX2c™CLEAR™) 

FOR T=1 TG 96 STEP 6 

ORUN GFX2c™SETDPTR™,3298 ,96) 
UFOR Y=@ TO 3 
UCOLOR=MODCY,2) 

ORUN GFX2C™"COLOR™, COLOR) 
UFOR X=1 TO 4 

READ DR$ 
ODRS="A"+STRECYI+DRE+STRSCTD 
ORUN GFXeCc™DRAW", DR$) 

UNEXT X 

LINEXT Y 

ORESTORE 

UONEXT T 

ORUN GFXec"COLOR", 3) 

WEND 

DATA SN PEs. BS a 
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DWE ND Device window end 


Syntax: RUN GFX2([path,|“DWEND”) 


Function: Deallocates the device window you initialized with 
DWSET and INIZ. If the window deallocated is the last device 
window on the screen, BASICO9 returns the screen memory to 
the system. DWEND automatically positions you in the next 
device window, a result similar to pressing (CLEAR]. You can 
use this function with DWSET to redefine a device window to 
a different type. 


Parameters: 
path The path number of the window you wish to 
end. Path can be a constant or variable. 
Examples: 


RUN GFX2C"DWEND") 
RUN GFX2CPATH,"DWEND") 
RUN GFX2C€3,"DWEND") 


Sample Program: 


From /TERM, this procedure temporarily opens a path to 
Window 3, displays the new window, draws a design, then 
returns to the /TERM screen and closes the path. 


PROCEDURE decorate 

MIDIM PATH, Ts YtINTEGER 

OPEN #PATH."/ Wa" WRITE 

ORUN GFX2CPATH,"DWSET",7,08,09,88,24,3,2,2) 
RUN GPX2CPATH, “SELECT? 

HY =1 

RUN GFA2CPATH, “COLOUR”, 3,2) 

FOR T=) T6 Tes STEP 3 

LY=Y+1 

ORUN GFX2@CPATH,"ELLIPSE",3298,96,T,Y) 
UNEXT T 

RUN GF XPCPATH, “COLOUR”. 1422 

FOR T2135 70 4 SIEP -6 
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RUN: GF FECPATH, “ELLIPSE” ,320.,936:,T.¥) 
Wie INTC S327 s/s THEN 

LY=#V¥+ 

UENDIF 

UNEXT T 

RUN GFA2ZCT. “SELECT? 
URUN GFX2@CPATH,"DWEND") 
UCLOSE #PATH 


WEND 
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DWPROTSW Device window protect switch 


Syntax: RUN GFX2([path,|“DWPROTSW”,“switch’’) 


Function: Lets you uwnprotect one device window and set other 
device windows on top of it. 


OS-9 on the Color Computer 3 normally uses a protected win- 
dowing system that does not allow window devices to overlap. 
Removing the window protection with DWPROTSW lets one 
device window exist on the same screen area as another win- 
dow device. Because this might destroy the contents of an 
unprotected window, you need to use care with this function. 


Parameters: 
path The route to the window you want to 
unprotect. 
switch Either OFF to turn off protection, or ON to 
turn on protection. The default is ON. 
Examples: 


RUN GFX2C"DWPROTSW", OFF 9) 
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DWSET Device window set 


Syntax: RUN GFX2([path,|“DWSET”,format,xcor,ycor, 
width, length, foreground, background, border) 


Function: Defines a device window. Normally, you first open a 
path to a window, then use DWSET to set the window format, 
location, size, and colors. 


Parameters: 

path The route to the window you are defining. 

format The code for the type of screen you want to 
establish. See Table 9.6 at the beginning of 
this section for the formats available. | 

xcor,ycor The coordinates (character column and row) of 
the upper left corner of the screen you want to 
create. 

width The width (in characters) of the new window. 

length The depth (in lines) of the new window. 

foreground The code for the window’s foreground color. 


background The code for the window’s background color. 


border The code for the window’s border color. 


Examples: 


RUN GPASC"DWSET™ ,06458,109,50519.20512,9) 


Sample Program: 


This procedure opens a path to Window 3, uses DWSET to define 
the new window, displays the new window, and draws a graphic 
lemon shape. It then uses SELECT to return to the /TERM win- 
dow or screen, deallocates Window 3, and closes the path. 
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PROCEDURE lemon 
DIM -PATHs leks ¥ Si NTEGER 
NOPEN #¥PATH,"/W3":WRITE 


URUN. GFASCPATH,“DWSET™,7,8,0,88,24,55,2,2) 
ERUN GFASCPATH, M“SELECT™) 


URUN GPX2CPATH,"COLOR™,@,29 
HPOR rsa) TO: 185 Srer os 
LUY=Y¥+t 

URUN GFXACPATH, "ELLIPSE” .320596.17 4572 
LINEAT. T 

UxXeT 

RUN. GFACCPATH, “COLOR” ,3,¢2 

FOR Te62 10 7 STEP <s 

RUN GFXECPATH, “ELLIPSE”, 328,96.%47 2 
GIF INTCT/33=T/3 THEN 

LIX=X+1 

ENDIF 

UNEXT T 

RUN GP ketls"SELECI™? 

URUN GFX2@CPATH,"DWEND") 


OCLOSE #PATH 
END 
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ELLIPSE Draw an ellipse 


Syntax: RUN GFX2([path,]“ELLIPSE”[,xcor,ycor], 
xrad, yrad) 


Function: Draws an ellipse with the center at the current 
draw pointer position or at the specified X,Y coordinates. The 
X coordinates are in the range 0-639. The Y coordinates are 
in the range 0-191. 


Parameters: 
path The route to the window in which you want to 
draw. 
xcor,ycor The coordinates for the ellipse’s center. If you 


omit these coordinates, ELLIPSE uses the 
current draw pointer position. 


xrad,yrad The radii of the ellipse’s length and height. 


Examples: 
RUN GFX2C"ELLIPSE",100,50) 


RUN GF ACC™ELLIFPSE™,10¢@,7255106.19) 


Sample Program: 


This program uses ELLIPSE to draw a graphic design shaped 
like a Christmas tree decoration. 


PROCEDURE xbulb 

UDIM 7. Yt IRTEGER 

LY =1 

URUN GFX2C"COLOR",3,2) 
URUN GFX2C™"CLEAR") 

FOR T#1. TO 188 STEP <3 
UY=Y+1 

URUN GFASCVELLIPSE™., 329, 96.7,7) 
UNEXT T 

RUN GFEX2C"COLOR™, 152) 
UFOoR T#tS8 TO? STEP =6 


a 
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UISUN. GF RCCPELLIPSE™, 320 -96,75 72 
LP INTCT YS 3261 7S THEN 

UY=Y+1 

UENDIF 

NEAT ff 

IRUN GFx2C"COLOR” 352) 

LEND 
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ERE OLIN E Erase to end of line 


Syntax: RUN GFX2([path,]“EREOLINE”’) 


Function: Deletes the portion of the current line from the cur- 
sor to the right side of the window. 


Parameters: 
path The route to the window in which you want to 
erase a portion of a line. 
Examples: 


RUN GFX2C"EREOLINE") 


Sample Program: 


This procedure uses EREOLINE to produce a series of steps 
down the screen. 


PROCEDURE steps 

DIM Task Ke INTEGER 
RUN. GPx2C’COLGR™ 2,532 
HIRUN GFX2C"CLEAR™) 
UORUN. GFX2¢"CGLOR™ ; 3,29 
FOR T=@ TO 2e 

NJeT*3 

RUN GF X20" CURKY™ 3.457) 
RUN GFX2@C"EREOLINE"™) 
UINEXT -f 
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ERE OW N DW Erase to end of window 


Syntax: RUN GFX2([path,]“EREOWNDW”) 


Function: Deletes all the lines in a window from the line on 
which the cursor is positioned to the bottom of the window. 


Parameters: 
path The route to the window in which you want to 
delete screen contents. 
Examples: 


RUN GFX2C"EREOQWNDW" ) 
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ERLINE Delete current line of text 


Syntax: RUN GFX2([path,]“ERLINE”) 


Function: Deletes the current line (on which the cursor is rest- 
ing) from the window but does not close the space. 


Parameters: 
path The route to the window in which you want to 
remove the contents of a screen line. 
Examples: 


KUN GPXe2C™ERLINE™) 


Sample Program: 


This procedure draws a bull’s-eye design, then slices it 
with the ERLINE function. 


PROCEDURE cut 

UDIM Xs ¥,R> 17, CULORSINTEGER 
UCOLOR=@ 

UX=328 

LIY=96 

URUN GFX2C"CLEAR™) 
UCOLOR=8 

FOR T=185 TO 18 STEP -19 
RUN GPASC CIRCLE 2%. ¥s7) 
UNEXT T 

UFOR T=14@ TO 328 STEP 19 
URUN GFX2¢C"COLOR™,COLOR) 
URUN. GF ACCP ILL’. T., 96) 
UCOLOR=COLOR+1 

NEAL | 

JFOR-TS2. TO 22 STEP 2 
RUN: GrArAecC™CORXY"".8. 71) 


URUN GFX2C"ERLINE') 
UNEXT -T 

UIRUN GFX2C"COLOR",3,2) 
JEND 


i 
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FILL Fun (paint) window 


Syntax: RUN GFX2([path,]“FILL”,[xcor,ycor]) 


Function: Paints an area with the current foreground color. 
Paint fills the portion of the window that is the same color as 
the pixel under the draw pointer. 


Parameters: | 
path | The route to the window in which you want to 
use the FILL function. 
xcor,ycor Are optional X- and Y-coordinates to reposi- 
tion the draw pointer before FILL begins. If 
you omit these coordinates, BASICO9 uses the 
current draw position. 
Examples: 


RUN GFX2C"FILL",100,100) 


Sample Program: 
This procedure draws and fills 100 boxes on a window. 


PROCEDURE colorbox 

DIM A.B84,0,0;,7,COLGR: INTEGER 
LICOLOR=8 

URUN GFX2c"CLEAR") 

UFOR T=1 TO 168 
UA=RNDCS5690) 

UB=RNDC151) 

UC=A+RNDC86 ) 

UD=B+RNDC 48) 
UCOLOR=COLOR+1 

UIRUN GFX2C"COLOR",COLOR)D 
UIRUN GFxec"BOXx",A,8,C,D) 
LIRUN. GF ACC™F ILL™, Ati, BF 12 
UNEXT T 
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F ON T Define font buffer 


Syntax: RUN GFX2((path,|“FONT”,group, buffer) 


Function: Defines a buffer from which BASICO9 gets the char- | 
acter font (style) for the current screen. Use the text/cursor | 
handling functions referenced in this section with the font you 
load. When you merge the Stdfonts file in your SYS directory | 
with a graphics window, you have the choice of three fonts 
from Buffers 1, 2, and 3, located in Group 200. You can also 
create your own fonts. FONT works only on graphics screen. 

See “Using Fonts” earlier in this chapter. 
| 


You must load the font you want to use into the defined buffer 
before using FONT. 


Parameters: 
path The route to the window in which you want to ww 
use an alternate font. 
group The group number of the buffer containing the 
font to use. 
buffer The number of the buffer containing the font 
to use. 
Examples: 


RUN GrAct'" FONT 288.2) 
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GC SET Set graphics cursor 


Syntax: RUN GFX2(“GCSET”,group, buffer) 


Function: Defines a buffer from which BASICO9 gets the 
graphics cursor. This lets you define your own cursor for 
graphics operations. To turn the graphics cursor off, use a 
group Number 0. You must execute this command to display a 
graphics cursor. Before using GCSET, you must merge the 
Stdcur file in the SYS directory to the window. 


Parameters: 


group The group number of the buffer containing the 
cursor image to use. See OS-9 Windowing 
System for information on the group to use. 


buffer The number of the buffer that contains the 
cursor image to use. See OS-9 Windowing 
System for information on the buffer to use. 


Examples: 


RUN GFX2C"GCSET™.1 a2 
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GET Get a block from the window 


Syntax: RUN GFX2([path,]“GET”,group, buffer,xcor, 
ycor,xsize, ysize) 3 


Function: Saves a window area Get/Put buffer. Use PUT to 
replace the image to the window. If you did not previously 
define the buffer, BASICO9 creates it. If you store the window 
data in a predefined buffer, the data must be the same size or 
smaller than the buffer. If not, BASICO9 truncates the data to 
the size of the buffer. (Also see PUT and DEFBUFF.) 


Parameters: 
path The route to the window where you want to 
save an image. 
group The group number of the Get buffer (1-199). 
buffer The Get buffer number (1-255). 
xcor,ycor The X- and Y-coordinates of the upper left cor- 
ner of the window image to save. The X- 
coordinates are in the range 0-639. The Y- 
coordinates are in the range 0-191. 
xsize The horizontal size of the window section to 
save. 
ysize The vertical size of the window section to save. 
Examples: 


RUN OF ASCE. 1 aoe OO e104 159 
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Sample Program: 


This procedure draws a character, loads it into a buffer, then 
repeatedly replaces the character to the window screen using 
PUT. Each new image erases the previous image, giving an 
impression of animation. 


PROCEDURE puttdown 


UDIM 
URUN 
URUN 
URUN 
URUN 
URUN 
URUN 
URUN 
URUN 
LIRUN 
URUN 
URUN 


LF OR 
URUN 
URUN 


URUN 
UEND 


UJ=19 


T,J4 INTEGER 

GF XeC"CLEAR™) 

OP ACE ELLIPSE" Seu 76, ley 
GFACC™CIRCULE™320.,98.,59 

OF Ae C™ COLOR” 72 

OF XZ" E ILE, 320,96) 

GPA2C*" COLOUR” 33 

Grae OC PILL" 320590) 
GFX2C"BAR",305,100,335,104) 
OP ACCVGET" 415154288, 85.50.23) 
Gr Xe OE T6142 1g lok seo? 
GPACOUPUT 71525288, 65) 


L=28 TO Salo STEP 6 


UJ=J+2 


OF AS POT ast ol and 


CER TT 


Gr AeCCYRILLBURP se 7.19 
GFX2C"CURON") 
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GPLOAD Load data into Get/Put buffer 


Syntax: RUN GFX2(“GPLOAD”, group, buffer,format, 
xdim, ydim, size) 


Function: Loads a buffer with image data that PUTBLK can 
use for window displays. If the Get/Put buffer is not created, 
BASICO9 creates it. If it is defined, the size of the data should 
not be larger than the buffer. 


Parameters: 


group 
buffer 
format 
xdim 


ydim 


size 


Examples: 


The group number you select, in the range 1- 
199, to let you group buffers. 


A number in the range 1-255 that you assign 
to the buffer you create. 


The type code of the screen format. (See Table 
9.4.) 


The X (horizontal) dimension of the stored 
block. 


The Y (vertical) dimension of the stored block. 


The size of the buffer in bytes. A buffer size 
can be in the range of 1 to 8 kilobytes, 
depending on available memory. 


RUN GFX2C"DEFBUFF™.1,5,86,1984,58,50809 
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INSLIN Insert line 


Syntax: RUN GFX2([path,]“INSLIN”’) 


Function: Moves the window lines at and below the cursor 
down one line. 


Parameters: 
path The route to the window in which you want a 
blank line. 
Examples: 


RUN GFXSC™INSLIN™)D 


Sample Program: 


This procedure draws a round face on the screen, then uses 
INSLIN and DELLIN to make a mouth appear to move. 


PROCEDURE chomp 

DIM 27s Fx INTEGER 

UDIM. RESPONSE+STRINGL1 1 
JRESPONSESs"™ 

URUN -GFXe2C™CLEAR™) 

HIRUN GFXec™CTRCLE™,328.,96,89) 
URUN GF x2C™COLOR™, 8,2) 

UIRUN: OF X2C"F ITLL". 320,969 

URUN -GFxX2c™COLOR™,2) 

URUN -GFx2C"CTROCLEY.285 88.12) 
URUN Greece VCTRCLE* 355.80 ,12) 
RUN GFXe2C"FILL™, 265,88) 

URUN GF Xe2C" Fr LLL 355.889 

RUN -GEA2CV CLR GLE 4315.96.30 
URUN GR AZO CIRCLE*, 325,96, 3) 
LIRUN- GF A2C™ARC™ 326.925.143.939 51s1412 
OIRUN. GF X2C "COLOR? 3.29 

RUN GFAZCM CIRCLE”. 269,772.39 
URUN: GF K2C™CIRCLE™,359,77,>232 
URUN GFX2C™CURKY™ 590,14) 
UREPEAT 
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URUN GFXec"INSLIN") 
UFOR X=1 TO 109 
UNEXT X 

DRUN GF X2C"DELLIN™) 
URUN INKEYCRESPONSE) 
WONT LL RESPONSE S?**” 
UEND 
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KILLBUFF Deallocate Get/Put buffer 


Syntax: RUN GFX2(“KILLBUFF”, group, buffer) 


Deallocates the indicated Get/Put buffer. You select group and 
buffer numbers when you define a buffer or when you load or 
get a window image. For more information on Get/Put buffers, 
see DEFBUFF, PUT, GET, and GPLOAD. 


Parameters: 
group The group number of the buffer you want to 
deallocate, in the range 1-199. Buffer Group 
Numbers 0 and 200-255 are reserved for OS-9 
system use. 
buffer The number of the buffer to deallocate, in the 
range 1-255. 
Examples: 


RUN. GP ASCK ILLBUPF 2155) 


Sample Program: 


This procedure draws a figure on a window screen, loads it 
into a buffer, then repeatedly places it in new locations on the 
screen. Each new PUT erases the previous image. 


PROCEDURE putdown 
UDIM Ke¥sTsJsINTEGER 
ORUN GFxec™CURDFF™) 

URUN GFxee2C"CLEAR™>} 

URUN -GFEX2C"ELLIPSE™ ,329,96,12 54) 
HRUN GFXe2C"CTROLE™$ 328,598,589 

URUN GF x2cC"COLOR".13 

RUN -GexASC'E PLE", 320.96) 

URUN GF Xec"cCOLER”™,3) 

URUN GFXA2C"FILL™, 328,998) 

RUN GFxX’ft" BAR”, 305,180,335, 1649 
URUN -GEKeC" GET" 1.1. 286>.85.,58,23) 
LRUN GEPACCNGED. yea ts lyo84232 
LIRUN OF XeC" PUT", 1,2,288,85) 
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LUJ=19 

FOR F228 70 S59 STer © 
UJ=J+2 

EIRUN- GFERSCVPUT. 75.14 Fada 
UNEXT T 

RUN GFXSC"KILLBUFE "1473 
URUN GFX2@c"CURON") 

UEND 
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LINE. Draw aline 


Syntax: RUN GFX2([path,|“LINE”[,xcor1,ycor1],xcor2, 
ycor2) 


Function: Draws a line in one of the following ways: 


@ From the current draw pointer to the specified X- and Y- 
coordinates. 


@ From the specified beginning X- and Y-coordinates to 
the specified ending X- and Y-coordinates. 


Parameters: 
path The route to the window in which you want to 
draw a line. 
xcorl1 ,ycor1 The optional beginning X- and Y-coordinates 
for the line. 
xcor2 ,ycor2 The ending X- and Y-coordinates for the line. 
Examples: 


RUN GP XALC™LINE” 192,128) 
SUN CFASC™C INE”, 850; 192,128) 


Sample Program: 


This procedure draws a sine wave of vertical lines across a 
window. 


PROCEDURE waves 

UDIM AsX,¥,;2t INTEGER 
LICALC=9 

UA=100 

URUN GFX2eCc"CLEAR") 
HIRUN GFXec™COLOR™.3,2) 
UFOR X=@ TO 638 STEP 1 
LICALC=CALC+.65 
HY=A-SINCCALC)#15 
UZ=Y¥+25 
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LIRUN: GE ACC" LING Ae Ts Aigee 
UNEXT X 
UEND 
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LO GIC Perform logic function 


Syntax: RUN GFX2(“LOGIC”,“function’”) 


Function: Causes BASICO9 to perform the specified logic func- 
tion on all data bits used by subsequent drawing functions. 
Once set, the logic function remains in effect until you turn 


LOGIC off. 


Parameters: 
function can be one of the following logical functions: 
OFF — no logic 
AND — performs AND logic 
OR — performs OR logic 
XOR  — performs XOR logic 
Examples: 


RUN GF X2C"LOGIC™ "AND" > 
RUN OFX2C™LOGIC™,"XOR") 


Sample Program: 


This procedure uses LOGIC to draw a horizontal bar across a 
background of multicolored vertical bars. Using XOR logic, the 
procedure causes the horizontal bar to change the color of each 
vertical bar. 


PROCEDURE logic 

UDIM A; 2,7T,X%,¥, COLOR: INTEGER 
IRON. -GPA2C"LUGTC™, MOFF™) 
URUN GFX2C"CLEAR") 

UCOLOR=@ 

UFOR T=8 TO. 619 STEP 290 
UCOLOR=COLOR+1 

URUN GFX2c"COLOR",COLOR) 
RUN GFX2C™BAR",T,@,T+20,190) 
NEAT 7 

URUN GFX2@c"COLOR",3,2) 

URUN: OF X2CV LOGIC’ "XOR™) 


ST LEE SSE ER LEST STA SS ATS LT SRD SE BEE TE DOE LEIA III IED EI IE TE AAD NE EE EEE a EEE AE EE EIT OSI II 
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UPOR- Est TH ke 
fIRUN GFX2€"BAR" ,8,88 ,629,1122 
UNEXT 7 

BRUN GFe2C"LUGiIo", "Grr 2 


LEND 
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OWSET Establish an overlay window 


Syntax: RUN GFX2([path,|“OWSET”,save switch,xpos, 
ypos,xsize, ysize, foreground, background) 


Function: Creates an overlay window on a previously existing 
device window. Reconfigures the current device window paths 
to use a new area of the screen as the current device window. 


Parameters: 


path The route to the window in which you want to 
set an overlay. 


save switch Either 0 or 1. A value of 0 tells BASICO9 not 
to save the overlaid area. A value of 1 tells 
BASICO9 to save the overlaid area and restore 
it when the new window closes. 


xpos The character column in which to start the 
new window (upper left corner). 

ypos The character row in which to start the new 
window (upper left corner). 

xsize The width of the new window in characters. 

ysize The depth of the new window in rows. 

foreground The foreground color of the new window. 


background The background color of the new window. 


Examples: 
RUN GFX2C"OWSET", @0,44,10,32,8,00,06) 


Sample Program: 


This procedure creates six progressively smaller overlay win- 
dows, labeling each. It then waits for you to press a key, after 
which it erases all the windows and leaves the original window 
intact. 
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PROCEDURE overwin 

HDEM Xs Yah ta ¥ Us los Be Le PLACEs INTEGER 
[DDIM RESPONSE ?#STRINGC1) 

UxX=8 \Y=@ 

OX1=80 \Y1=24 

UPLACE=33 

UOFOR T=1 TO 6 

GIF Tee OR T=6 THEN 

UB=3 

VELSE B=2 

LIENDIF 

ORUN GrieCV ONSET ot otis PSN ls Ye Bef 2 
OX=X+6G \Y=Yre2 

OX1=X1-12 \Y1=Y1-4 

FOR Jet TE 5 

DPRINT TABCPLACE); “Overlay Screen “; T 
UNEXT J 

LIPLACE=PLACE-6 

UNEXT T 

OPRINT “Press A Key..." 

GET #1 RESPUNSE 

LJFOR T=1 TG 6 

HIRUN GFX2Cc"OQWEND") 

CINEXT. T 

LIEND 
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PALE TTE Set color for palette registers 


Syntax: RUN GFX2((path,]“PALETTE”,register,color) 


Function: Sets palette colors. Lets you install any of the Color 
Computer’s 64 colors in the palette for use with text and 
graphics. 


Parameters: 
path The route to the window where you want to 
change palette colors. 
register The number of the register in which you want 
to install a new color. 
color The code of the new color you want to install. 
Examples: 


SUN GPX2C™"PALETTE" 13,32) 


Sample Program: 


This procedure draws a series of bars and circles, then repeat- 
edly changes their colors using PALETTE. 


PROCEDURE palette 

UDIM T,K,J,X,Y,COLOR: INTEGER 
UDIM RESPONSE:STRING[1] 

URUN GFXeEC™COLOR™,332.2) 
UICOLOR=8 

HIRUN GFX2Cc™CLEAR") 

URUN GFX2C"CUROFF"') 

UFOR Y=@ TO 23 STEP 3 

URUN GFX2Cc"COLOR"™,COLOR) 
UIRUN GFX2C"BAR",@,Y,639,Y+3) 
HICOLOR=COLOR+1 

HIF COLOR=2 THEN 
HUCOLOR=COLOR+1 

LENDIEF 

LINEXT Y 

FOR Y=164 TO 185 STEP 3 
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URUN GFReC"COLOR™, COLOR) 

URUN GF AZLS “BAR, 8.75539, %* 22 

UCOLOR=COLOR+1 ) 
ONEXT ¥ wo 
LICOLOR=@ 

LFOR K=45 70 178 STEP 48 

CUFOR T=109 TO 588 STEP 198 

RUN: GF AZo" COLOR, 32 

RUN GF XEC"CIROLE™, Thy o82 

URUN GFX2c"COLOR",COLOR) 

LIRUN GPeACV PILE”, 7 4K2 

UCOLOR=COLOR+1 

HIF COLOR#=2 THEN 

UCOLOR=COLOR+1 

UENDIF 

UNEXT T 

NEAT 

UREPEAT 

UX=RNDC63) 

UREPEAT 

LY=RNDC16)+1 

UUNTIL Y¥<>2 wo 
LUIRUM “GF XZKka" PALETTE; ¥5X%9 

URUN INKEYCRESPONSE ) 

UUNTiL RESPONSES" 

HRUN GFX2C"DEFCOL") 


URUN GFX2Cc"CURON') 


END 
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P ATTE RN Select pattern buffer 


Syntax: RUN GFX2([path,]“PATTERN”, group, buffer) 


Function: Selects the contents of a preloaded Get/Put buffer as 


a pattern for graphics functions. Although PATTERN can use 
a buffer of any size, it uses a specific number of bytes, depend- 
ing on the screen format in use: 


Color Pattern Bits 
Mode Array Size Per Pel 
02 4 bytes x 8 bytes = 32 bytes 1 
04 8 bytes x 8 bytes = 64 bytes 2 
16 16 bytes x 8 bytes = 128 bytes 4 


The pattern array is a 32 x 8 pel representation of graphics 
memory. It takes the current color mode into consideration to 
define the number of bits per pel and pels per byte. If the 
buffer is larger than the number of bytes required, PATTERN 
ignores the extra bytes. BASICO9 uses the selected pattern 
with all draw commands until you change the pattern or turn 
off the pattern function by specifying a group and buffer num- 
ber of 0. 


Parameters: 
path The route to the window in which you want to 
use a new graphics pattern. 
group The group number of the buffer you want to 
use for a graphics pattern. 
buffer The buffer number that you want to use for a 
graphics pattern. 
Examples: 


RUN GFACC™PATTERN™, 1,323 
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Sample Program: 


This procedure loads the current window data at location 0,0 
into a buffer to use as a draw pattern. It then draws a circle and 
fills the circle with the pattern in the buffer. 


PROCEDURE pattern 

UDIM X.¥5T#LNTEGER 

DRUN “GPASC "OE T*.15795 05,855.59 
URUN GFX2ec"COLOR", 4) 

URUN. GFxeC"CLEAR™D 

HRUN GFEXe2C'CIRCLE™..328.,.96,1988) 
URUN GFX2c"FILL™, 329,96) 
WRUN GER2C”PATIERN = 1412 
LIRUN GFXec™"COLOR", 3) 

LIRUN GFXec"FILL",320 ,96) 
LIRUN GFXeC™"PATTERN",@,90) 
LIEND 
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P OIN fh Mark a point 


Syntax: RUN GFX2([path,]“POINT”[,xcor,ycor]) 


Function: Sets the pixel at the current draw pointer position 
or at the specified coordinates to the current foreground color. 
If you do not specify coordinates, POINT sets the pixel at the 
draw pointer. 


Parameters: 
path The route to the window in which you want to 
turn on the specified pixels. 
xcor,ycor Optional coordinates for the POINT function. 
The X-coordinates are in the range 0-639. The 
Y-coordinates are in the range 0-191. 
Examples: 


RUN GFX2C™POINT"™) 
RUM VFACC PRINT" .192,128) 


Sample Program: 


This procedure uses POINT to produce a swirl design on a win- 
dow screen. 


PROCEDURE point 

UBASE @ 

UDIM X€29),YC20): INTEGER 
LOL: Ta Rods Ke INTEGER 


LIRUN GFX2C"CUROFF'') 
RUN. GPA2C"CLEAR™) 
WFOR T= TO 288 STEP <3 
UJ=J+4 

UFOR R=@ TO 11 
UXCRI=INTCT*#SINC30*R+K))+320 
LYCRI=INTCJU*COSC38*R+K))+96 
UIRUN: GFA2C™ POINT"; XORD, ¥CRII 
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UK=K+1 

UNEXT R 

LINEAL of 

ORUN GFX2C"CURON") 


UEND 


9-114 


Displaying Text and Graphics / 9 


PROPSW Proportional space switch 


Syntax: RUN GFX2([path,|“PROPSW”,“switch’’) 


Function: Enables or disables the automatic proportional spac- 
ing of characters on graphic screens. 


Parameters: 
path The route to the window in which you want to 
use proportional character spacing. 
switch Either OFF to turn proportional spacing off, or 
ON to turn proportional spacing on. The 
default setting of the switch is OFF. 
Examples: 


RUN GFA2C"PROPSW™, "ON" 


Sample Program: 


This procedure produces a demonstration of the BASICO9 propor- 
tional spacing function. 


PROCEDURE proport 
UDIM LINE SS TRING 
TIDIM LETTER?STRINGL 1 3 
HDOM TodeKsFLAGt INTEGER 
HORUN GFX2@c"CLEAR") 
UFLAG=1 

HPOR T=. TH te 
UREAD LINE 

FOR Jd=4+ TO LENCLINED 


DULETTER=MID$CLINE,J,1) 


iP LET TeR<o**!* Anp LETTERS? "Ss"  Laeh 
PRIA LErers 

WENDIF 

CLEP EP TE 2 EN 


UFLAG=FLAG*-1 
HIF FLAG>@ THEN 
DRUN GFX2C"FROPSW" "ORR 2 
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NELSE 

ORUN GFX2C"PROPSW", 
OENDIF 

OENDIF 

OIF LETTER="#" THEN 
OPRINT CHR$(€34); 
OENDIF | 


"WANS 
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UNEXT J | 
LUPRINT | 
UNEXT T 

UPRINT \ PRINT 

LEND 

UDATA "This is a demonstration of" 

UDATA "!Proportional Spacing! using" 

LDATA "BASIC@9’s GFX2 module." 

UDATA "" 

DATA “lThe quick brawn fox jumped..." 

UDATA “The quick brown fox jumped..." 

UDATA 

DATA "Use the command" 

DATA "!RUN GFX2C#PROPSW# , #ON#)E" 

UDATA “to turn proportional spacing on." 

DATA "Use !RUN GFX2C#PROPSW#, #OFF et" 

UDATA “to turn proportional spacing off" 
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P UT Put a saved data block on the window 


Syntax: RUN GFX2([path,]“PUT”,group, buffer, 
xcor,ycor) 


Function: Places the image in the specified Get/Put buffer on 
the window. PUT requires only the group and buffer numbers 
and the window coordinates for the upper left corner of the 
image. The GET function saves the dimensions of the block in 
the buffer. PUT automatically handles window format 
conversion. 


Parameters: 
path The route to the window where you want to 
place a pre-saved image. 
group The group number of the buffer in which to 
save the window data. 
buffer The buffer number in which to save the win- 
dow data. 
xcor,ycor The X- and Y-coordinates of the upper left cor- 
ner of the window position. The X-coordinates 
are in the range 0-639. The Y-coordinates are 
in the range 0-191. 
Examples: 


RUN GPeECVPUT".1,5,1796, 589 
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Sample Program: 


This procedure draws a character, loads it into a buffer, then 
repeatedly replaces the character to the window screen using 
PUT. Each new image erases the previous image, giving an 
impression of animation. 


PROCEDURE putdown 
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UDIM: A>¥4 base NIEGER 

URUN GFX2C"CUROFF') 

URUN GFX2C"CLEAR") 

LIRUS GPRe2C™ELLIPSE™, 328,906,124 4) 
HIRUN: GFXAC" CIRCLE”, s28,98,52 
URUN GFX2c"COLOR",1) 

URGUN GPASC FILL, 328,96) 

URUN OF XSC"COLUR" «32 

URUN GFXe2c"FILL", 328,90) 

URUN GFX2C"BAR",305,1080,335,104) 
URUN GP ACZCYMGET™, 15175268 ,85,58,2e2) 
LIRUN °“GFREC"GE to tyeg hs ty SBe2o? 
RUN GRAS rut 1424 286,85) 
LUJ=10 

LF GR Te2@ 10 S59 STEP G 

LJ=J+2 

RUN Grr PUT etal 4s Taal? 

UNEXT T 

URUN GPAetV RI LE BUR rss 1 ah? 

URUN GFX2c"CURON"') 

UEND 
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PUTGC Put graphics cursor 


Syntax: RUN GFX2([path,]“PUTGC”,xcor,ycor) 


Function: Places and displays the graphics cursor at the speci- 
fied location. Use screen relative coordinates for this function, 
not window relative coordinates. The horizontal range is 
0-639. The vertical range is 0-191. 


Parameters: 
path The route to the window where you want to 
display a graphics cursor. 
xcor,ycor The screen coordinates for the cursor location. 
The X coordinates are in the range 0-639. The 
Y coordinates are in the range 0-191. 
Examples: 


RUN GPxXeC™PRUTGC™,108,5) 


Sample Program: 


This procedure displays the available graphic cursors stored in 
group 202. Before this procedure can work, you must merge the 
Stdptrs file in the SYS directory of your system disk with the 
window you are using. For instance, if your system diskette is in 
Drive /DO, merge Stdptrs with Window 1, by typing: 


merge /d@/sys/stdptrs >» /w' 


PROCEDURE viewcur 

UDIM T,Z22¢ENTEGER 

LIRUN GFXec"CLEAR") 

LIFOR T=1 TO 7 

PIR or RSE" OCSET 282.12 


LIRUN. GFA2C™PUTGC™, 328,96) 
UFOR Z=1 TO 6080 

REA T 2 

UNEXT T 

UIRUN GFX2C"GCSET",@,9) 
END 
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RE VON Reverse video on 
RE VOF F Reverse video off 


Syntax: RUN GFX2([path,]“REVON”) 
RUN GFX2([path,]“REVOFF’’) 


Function: Enables or disables reverse video characters. Once 
set, reverse video remains in effect until you execute the 
reverse video off function. 


Parameters: 
path The route to the window in which you want to 
display reverse characters. 
Examples: 


RUN GFX2C™REVON") 
RUN GFAZC’REVOFF™) 
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SCALESW Enable/disable scaling 


Syntax: RUN GFX2([path,]“SCALESW”,“switch’’) 


Function: Enables or disables scaling when drawing on var- 
iously formatted windows. Scaling in windows is normally on. 
If scaling is off, coordinates are relative to the window origin 
coordinates. Scaling does not affect text. 


Parameters: 
path The route to the window where you want to 
turn scaling off or on. 
switch Either OFF (disable scaling) or ON (enable 
scaling). 
Examples: 


RUN “OF Ae CV SCALESH*. "BFF 2 


Sample Program: 


This procedure runs a routine of drawing a design in overlay 
windows twice. The routine runs once with scaling off and once 
with scaling on. After the first routine pauses, press the space 
bar to see the second demonstration. 


PROCEDURE scale 

UDEM Xie Vek 1a ¥1. 2 fo Byda Rel Zt INTEGER 
DIM RESPUNSEsSTRINGET I 

LIRUN GFX2@Cc"CLEAR") 

LIFOR J=1 TO 2 

DIF J=1 THEN 

URUN GExAAc™SCALESW™..* OFF") 
ELSE 

UIRUN GFrYSC’SCALESN”,"ON"™) 
HENDIF 

UX=@ \Y=@0 \X1=8@ \Y1=24 
(FOR T=1 TO 4 

HIF T=2 OR T=6 THEN 

UB=3 


9-121 


BASICO09 Reference 


DELSE Be=2 

DENDIF 

REN GPeeEC™OWSET ot aka lak 13% 138s TD 
OFOR R=1 TO 35 

UW=48*SINCR) +170 

0Z=25*COSCR)I+45 

UIRUN GEXZE"C I RCLE™ WZ, 38) 

UNEXT R 

OX=X+6 \Y=Y+2 \X1=X1-12 \Y¥1=Y1-4 
PINEALE 

UPRINT “Press A Kéyous™5 

UGET #1.,RESPONSE 

UFOR T=1 TO 4 

URUN GFX2C"OWEND") 
ONEXT T 

OINEXT J 

LEND 
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SE LE CT Select next window 


Syntax: RUN GFX2([path],“SELECT”) 


Function: SELECT causes a window to display if the proce- 
dure is operating in the active window. If the procedure is not 
in the active window, the newly selected window displays 
when you press (CLEAR]. If you do not specify a path, BASICO9 
selects the device using the standard input, standard output, 
and standard error paths, Paths 0, 1, and 2. 


Parameters: 


path The path to the window to select. 


Examples: 
RUN GFX2C"SELECT") 
RUN GFX2C1,"SELECT") 


RUN GFX2CPATH; "SELECT" ) 


Sample Program: 


From /TERM, this procedure temporarily opens a path to 
Window 3, creates the window format, and uses SELECT to dis- 
play the new window. It draws a design, then returns to the 
/TERM screen and closes the path. 


PROCEDURE design 
DDIM PATH, TY: INTEGER 
UGPEN #PATH.“/W3S":WRITE 


URUN OP XSCPATH,"DWSET™,.5,0,0;80,249,;352,29 


URUN GFX2CPATH, "SELECT" ) 


LY = 14 

UeoR T=4 TO 2g8 STEP 3 

yey ey 

Rah GFACCPATO. “ELLIPSE™. 320596. 1572 
AEA oF 


RUN GFACOPATH, “COLOR”, 1,29 
UFUR T#=20¢@ TO 1 STEP -6& 
RUN GPKeECPATH, ELLIPSE", 3285,96.75 72 
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UIF INICT/3)*T73 THEN 
LY=Y¥+1 

UENDIF 

UNEXT T 

UIRON -GrAecl ,MSELECT™ >) 
URUN GFX2CPATH,"™DWEND") 
UCLOSE #PATH 

UEND 


9-124 


Displaying Text and Graphics / 9 


SETDPTR Set draw pointer 


Syntax: RUN GFX2([path,|“SETDPTR”,xcor,ycor) 


Function: Places the draw pointer at the specified coordinates. 
The draw pointer selects the beginning point of the next 
graphics draw function (such as CIRCLE, LINE, BOX, and so 
on), if you do not supply other coordinates. 


Parameters: 
path The route to the screen where you want to set 
the draw pointer. 
xcor,ycor The screen coordinates for the draw pointer 
location. The X-coordinates are in the range 
0-639. The Y-coordinates are in the range 0- 
191. 
Examples: 


RUN GEXSC™SETDPTR™, 188,59) 


Sample Program: 


This procedure uses coordinates from a DATA statement for set- 
ting the draw pointer to create a series of star shapes. 


PROCEDURE star 

UDIM Xs ¥s 1 okt LRTEGER 

UIPRINT CHRS$CT2) 

FoR v=) To 198 

READ X,Y 

UIRUN GPXY2C™SETDPIR"™, XJ, Y¥ed+J2 
UFOR T=1 TO 5 

UREAD X,Y 

URUN GFASC™LINE™ X40, Y Fd 4d) 
NEXT. T 

OINEXT. J 

UDATA 328,46,448,146,200 ,84,4480,84,208,146,3208,46 
WIEND 


9-125 


BASICO9 Reference 


UNDLNON Underline characters on 
UNDLN OF F Underline characters off , 


Syntax: RUN GFX2([path,|“UNDLNON”) 
RUN GFX2([path,|“UNDLNOFF’”’) 


Function: Enables or disables character underline. After you 
execute UNDLNON, all characters displayed are underlined 
until you execute UNDLNOFF. The default is UNDLNOFF. 


Parameters: 
path The route to the window where you want to 
use underline characters. 
Examples: 
RUN GFX2C™"UNDLNON") ww 


RUN GFX2C™UNDLNOFF") 
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BASIC09 Quick Reference 


This chapter contains a quick reference of all BASICO9 com- 
mands, statements, and functions. It includes commands for pro- 
gramming, editing, and debugging, as well as the Commands 


mode commands. 


The following chart lists all BASICO9 keywords that you can use 


in a procedure. 


Statements and Functions 


Command 


ABS 
ACS 
ADDR 
AND 


ASC 


ASN 
ATN 
BASE 


BYE 
CHAIN 


CHD 
CHRS$ 


CHX 
CLOSE 


COS 


Description 
Returns the absolute value of a number. 
Calculates the arccosine of a number. 


Returns an integer value which is the abso- 
lute memory address of a variable, array, or 
structure in a process’s address space. 


Generates the logical AND of two Boolean 
values. 


Returns the ASCII code of the first charac- 
ter in a string. 


Calculates the arcsine of a number. 
Calculates the arctangent of a number. 


Sets the lowest array or data structure sub- 
script in a procedure to either 0 or 1. 


Ends execution of a procedure and termi- 
nates BASICO9. 


Executes a module, passing arguments if 
appropriate. 


Changes the current data directory. 


Returns the ASCII character represented by 
a specified integer. 


Changes the current execution directory. 


Deallocates the specified path to a file or 
device. 


Calculates the cosine of a number. 


10-1 


BASICO9 Reference 


Command 
CREATE 


DATES$ 
DEG 
DATA 


DELETE 
DIM 


DO 
ELSE 
END 


ENDEXIT 
ENDIF 
ENDLOOP 
ENDWHILE 
EOF 

ERR 


ERROR 

EXITIF/ 
ENDEXIT 

EXP 

FALSE 

FIX 


FLOAT 
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Description 


Opens a path and establishes a new file on 
disk. 


Returns the computer’s current date and 
time. 


Causes BASICO9 to calculate angles in 
degrees. 


Stores data in a procedure to be accessed 
by the READ statement. 


Deletes a file from disk. 


Declares simple variables, arrays or complex 
data structure for size and type. 


See WHILE/DO/ENDWHILE. 
See IF/THEN/ELSE/ENDIF. 


Terminates execution of a procedure. 
Returns to the calling procedure or to 
BASIC09’s command mode. Displays the 
specified text. 


See EXITIF/ENDEXIT. 

See IF/THEN/ELSE/ENDIF. 
See LOOP/ENDLOOP. 

See WHILE/DO/ENDWHILE. 
Tests for the end of a disk file. 


Returns the error code of the most recent 
error. 


Generates the specified error. 


Tests conditions in a loop. The procedure 
exits the loop if the condition is true. 


Calculates e (2.71828183) raised to the 
specified value. 


A Boolean function that always returns 
FALSE. 


Rounds a real number and converts it to an 
integer. 


Converts a byte or integer value to a real 
number. 
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Command 
FOR/NEXT 


GET 


GOSUB/ 
RETURN 


IF/THEN/ELSE/ 
ENDIF 


INKEY 
INPUT 
INT 

Oy) KILL 
LAND 
LEFT$ 


LEN 
LET 
LNOT 


LOG 
LOG10 


LOOP! 
ENDLOOP 


>) Lor 


Description 


Creates a program loop of a specified num- 
ber of repetitions. 


Reads an element or a data structure from 
a binary file or a device. 


Transfers program control to a specified 
subroutine. RETURN sends execution back 
to the calling routine. 


Evaluates an expression and performs an 
operation if the conditions are met. Includ- 
ing ELSE causes an alternate operation if 
the conditions are false. 


Stores the character of a keypress in a 
string variable. 


Causes a procedure to accept input from 
the keyboard or other specified device. 


Returns the largest whole number less than 
or equal to the specified value. 


Unlinks a procedure. (Removes it from 
BASIC09’s directory.) 


Performs a bit-by-bit logical AND on 
two-byte, or integer, values. 


Returns the specified number of characters, 
from the leftmost portion of a string. 


Returns the length of the specified string. 
Assigns a value to a variable. 


Performs a bit-by-bit logical NOT function 
on two-byte, or integer, values. 


Calculates the natural logarithm. 
Calculates a base 10 logarithm. 


Establishes a loop. Use EXITIF and 
ENDEXIT to test the loop and exit when a 
specified condition is true. 


Performs a bit-by-bit logical OR on two- 
byte, or integer, values. 
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Command 
LXOR 


MID$ 


MOD 


NEXT 
NOT 


ON ERROR/ 


GOTO 
ON/GOSUB 


ON/GOTO 


OPEN 
OR 
PARAM 
PAUSE 
PEEK 


PI 
POKE 


POS 
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Description 


Performs a bit-by-bit logical EXCLUSIVE 
OR on two-byte, or integer, values. 


Returns the specified number of characters, 
beginning at the specified position in a 
string. 


Returns the modulus (remainder) of a divi- 
sion operation. 


See FOR/NEXT. 


Returns the logical complement of a Boolean 
value. 


Traps errors and transfers control to the 
specified line number. 


Evaluates an expression. Then, selects from 
a list the line number that is in the posi- 
tion indicated by the result of the expres- 
sion. Procedure execution transfers to the 
selected line. 


Evaluates an expression. Then, selects from 
a list the line number that is in the posi- 
tion indicated by the result of the expres- 
sion. Procedure execute jumps to the 
selected line. 


Opens an I/O path to an existing file or 
device. 


Performs a logical OR on two Boolean 
values. 


Describes the parameters a called proce- 
dure expects from a calling procedure. 


Suspends execution of a procedure, and 
enters the Debug mode. 


Returns the byte value of a memory 
address. 


Represents the constant 3.14159265. 


Stores a byte value at a specified memory 
address. 


Returns the current character position of 
the print buffer. 


Command 
PRINT 


PRINT USING 
PRINT# 
PRINT# USING 


PUT 
RAD 


READ 


REM 


REPEAT/UNTIL 
RESTORE 


RETURN 
RIGHT$ 


RND 


RUN 
SEEK 
SGN 
SHELL 


SIN 
SIZE 


SQ 
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Description 


Sends the specified characters or values to 
the display. 


Sends characters or values to the display, 
using the specified format. 


Sends the specified characters or values to 
the specified path. 


Sends characters or values to the specified 
path using the specified format. 


Writes data to a random access file. 


Causes BASICO9 to calculate angles in 
radians. 


Accesses data from procedure DATA lines or 
from files or devices. 


Indicates that the following characters in a 
procedure line are comments and are not to 
be executed. Also use (* OE, 


Establishes a loop that executes until the 
specified condition is met. 


Restores the DATA pointer to the first data 
item or to a specified line. 


See GOSUB/RETURN. 


Returns the number of characters specified, 
from the rightmost portion of a string. 


Returns a random number from a specified 
range. 


Calls another procedure for execution. 
Changes the file pointer address. 
Determines the sign of a number. 


Calls an OS-9 command or program for 
execution. 


Calculates the sine of a specified value. 


Returns the number of bytes assigned to a 
variable, array, or complex data structure. 


Calculates a value raised to the power of 
two. 
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Command 
SQR/SQRT 


STEP 


STOP 


STR$ 
SUBSTRING 


SYSCALL 
TAB 


TAN 
TRIM$ 


TRON/TROFF 
TRUE 

TYPE 

UNTIL 

USING 

VAL 


WHILE/DO/ 
ENDWHILE 
WRITE 


XOR 
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Description 


Calculates the square root of a positive 
number. 


Sets the size of increment in a FOR/NEXT 
loop. 


Terminates the execution of all procedures 
and returns to the BASICO9 Command 
mode. 


Converts numeric data to string data. 


Returns the starting position of a sequence 
of characters in a string. 


Executes an OS-9 System Call. 


Begins a print operation at the specified 
column. 


Calculates the tangent of a value. 


Strips trailing spaces from the specified 
string. 


Turn the trace mode on and off. 
Returns the Boolean value of TRUE. 
Defines a new data type. 

See REPEAT/UNTIL. 

See PRINT USING. 

Converts a string to an integer. 


Executes a loop as long as a specified condi- 
tion is true. 


Writes data in ASCII format to a file or 
device. 


Performs a logical EXCLUSIVE OR on two 
Boolean values. 
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Commands by Type 


Statements 

BASE 0 DIM 

BASE 1 ELSE 

BYE END 

CHAIN ENDEXIT 
CHD ENDIF 

CHX ENDLOOP 
CLOSE ENDWHILE 
CREATE ERROR 

DATA EXITIF/THEN 
DEG FOR/TO/STEP 


DELETE 


GET 


GOSUB 
GOTO 
IF/THEN 
INPUT 
KILL 

LET 

LOOP 
NEXT 

ON ERROR/GOTO 
ON/GOSUB 
ON/GOTO 


Transcendental Functions 


ACS COS LOG10 
ASN EXP PI 
ATN LOG 

Numeric Functions 
ABS LAND MOD 
FIX LNOT RND 
FLOAT LOR SGN 
INT LXOR 

String Functions 
ASC LEFT$ RIGHTS 
CHR$ LEN STR$ — 
DATE$ MID$ SUB 
INKEY 

Miscellaneous Functions 
ADDR FALSE SIZE 
EOF PEEK TAB 
ERR POS TRUE 


OPEN 
PARAM 
PAUSE 
POKE 
PRINT 
FUE 
RAD 
READ 
REM 
REPEAT 
RESTORE 


SIN 
TAN 


SQ 
SQR 
SQRT 


TRIM$ 
VAL 
STR 


SYSCALL 


RETURN 
RUN 
SEEK 
SHELL 
STOP 
TROFF 
TRON 
Leek 
UNTIL 
WHILE/DO 
WRITE 
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Data Types 


The following list shows the BASICO9 data type you can specify 
when defining a variable. 


Type Function 

BOOLEAN Returns TRUE or FALSE 

BYTE Specifies that a numeric variable is to store 
single-byte values. 

INTEGER Specifies that a numeric variable is to store 
integer (two-byte) values. 

REAL Specifies that a numeric variable is to store 
real (five-byte) values. 

STRING Specifies that a variable is to store ASCII 
characters. 


Types of Access for Files 


You can use the following parameters with the CREATE and 
OPEN commands. Check the individual commands for informa- 
tion on which parameter to use with which command. 


Parameter Function 

DIR Lets BASICO9 access a directory-type file 
for reading. Do not use with UPDATE or 
WRITE. 

EXEC Lets BASICO9 access the current execution 
directory rather than the current data 
directory. 

READ Sets the file access mode for reading. 

WRITE Sets the file access mode for writing. 

UPDATE Sets the file access mode for both reading 


and writing. 
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Command Mode 


The following chart lists the commands available from the 
BASICO9 Commands mode: 


Command 


$ 
BYE or 


CHD 


CHX 
DIR 


EDIT or E 
KILL 
LIST 
LOAD 


MEM 


PACK 


RENAME 
RUN 
SAVE 


Function 


Calls the shell command interpreter to exe- 
cute an OS-9 command. 


Returns you to the OS-9 system or to the 
program that called BASICO9. 


Changes the current data directory. 
Changes the current execution directory. 


Displays the name, size, and variable stor- 
age requirement of each procedure in the 
workspace. 


Enters the procedure editor/compiler mode. 


Removes one or more procedures from the 
workspace. 


Displays a formatted listing of one or more 
procedures. 


Loads all procedures from a file into the 
workspace. 


Displays current workspace size or reserves 
a specified amount of memory for the 
workspace. 


Performs a second compilation and stores 
the resulting file in the execution directory. 


Changes a procedure’s name. 
Causes a procedure to execute. 
Writes one or more procedures to disk. 
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Edit Commands 


The following chart lists the commands available from the Edit 


mode: 


Command 


+num 


+ * 


—num 


— * 


text 
line 
line {ENTER 


c/str1/str2/ 
c*/str1/str2 


r line 
r line num 


s/str 
s*/str 
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Function 
Moves the edit pointer to the next line. 


Moves the edit pointer forward a specified 
number of lines. 


Moves the edit pointer past the last line. 


Moves the edit pointer back a specified 
number of lines. 


Moves the edit pointer to the first line. 


A space followed by text inserts an unnum- 
bered line before the current line. 


Typing a line number with or without text 
following it inserts the line into the 
procedure. 


Moves the edit pointer to the line line. 
Changes the text str1 to the text str2. 
Changes all occurrences of str1 to str2. 
Deletes the current line. 

Deletes all the lines in the procedure. 

Lists the current line. 

Lists all the lines in the current procedure. 
Terminates the edit session. 


Renumbers lines from the first line number, 
in increments of 10. 


Renumbers all numbered lines in incre- 
ments of 10. The first line number is 100. 


Renumbers lines from line in increments of 
10. 


Renumbers lines from line, in increments of 
num. 


Searches for the first occurrences of str. 
Searches for all occurrences of str. 
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Debug Commands 


The following table lists all the Debug commands and what they 


accomplish: 


Command 
$command 


BREAK 


CONT 
DEG/RAD 


LET 
LIST 


PRINT var 
STATE 


STEPnum 


TRON/TROFF 


Function 


Tells BASICO9 to execute the specified OS-9 


command or program. 


Sets a breakpoint at the specified 
procedure. 


Causes procedure execution to continue. 


Selects either degrees or radians as the unit 
of angle measurement for trigonometric 
functions. 


Displays the procedures in the workspace. 


Leaves the Debug mode for the System 
mode. 


Assigns a new value to a variable. 


Displays a source listing of the suspended 
procedure. 


Displays the value of the specified variable. 


Lists the nesting order of all active 
procedures. 


Causes execution of the suspended proce- 
dure in specified increments. 


Turns the trace function on and off. 
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BASICO0O9 Command Reference 


BASICO9 is made of keywords (functions and statements) that 
you use, with their parameters, to instruct the computer to per- 
form certain operations. 


This chapter is a complete reference for all of BASICO9’s 
keywords. 


Keyword Format 
The reference to each keyword is organized in this manner: 
@ The keyword. 


e The proper syntax (spelling and form) for using the 
keyword. 3 


e A brief description of the keyword’s purpose or effect. 


e@ Descriptions of any parameters or arguments for the 
keyword. 


@ Notes about special features or requirements of the key- 
word, when appropriate. 


@ One or more examples for using the keyword. 
@ One or more sample procedures. 


This format can vary slightly, depending on the complexity of 
each keyword. For instance, some keywords require parameters 
or arguments, and others do not. Some keywords are self- 
explanatory and do not require a sample procedure. 


The Syntax Line 


The second line in each command or keyword reference is the 
syntax line. This line uses keyword constants and keyword vari- 
ables to show you how to construct a command line. Constants 
are words, numbers, or symbols that you type exactly as they 
appear. Variables are words that only represent the actual 
words, numbers, or symbols that you must supply for the 
command. 
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All variables are italic. When you see an italicized word, you 
know that you must supply some other word, name, symbol, or 
value in place of that word. If a word, symbol, or value is not 
italicized, type it exactly the way it appears in the syntax line. 


The syntax line also uses symbols to help you understand how to 
construct a command line. These symbols are: 


[] Words, names, value, or symbols contained between 
right and left brackets are optional. You can use them 
or not, depending on what you want to accomplish with 
the command. 


. Ellipsis indicates that the last parameter can be 
repeated. 


The following syntax line for DELETE requires only one param- 
eter, the variable pathname. 


DELETE “pethnamne” 


Because pathname is italicized, you know that you must replace 
it with other text—in this case the pathlist to the file you want 
to delete. If you wanted to delete a file named Test from the 
ROOT directory of Drive /D1, this syntax line tells you that you 
must type: 


delete "/d1i/test" 


Other syntax lines are more complex, such as the line for 
CREATE: 


CREATE #path,“pathlisti” Laccess model 
[+access model[t+...] 


This line tells you how to create a path to a file or device. 
Because the number symbol (#) is not italicized, you type it 
after the blank space following the keyword. However, 
path,pathlist, and access mode are all italicized. You must 
replace them with other names or values. 


The access mode variable is contained within brackets. This tells 
you that it is optional. You can include an access mode, or not. If 
you don’t, BASICO9 opens the path in the Update Mode. 


The second access mode shows that the command allows two 
access mode parameters, preceded by a plus symbol. The ellipsis 
show that you can have even more access mode parameters. 
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Other syntax lines show that no parameters are required, such 
as: 


DATE$ 


This command returns the current date. There is nothing it 
requires, and you can do nothing else with it. 


Sample Programs 


The sample programs in this chapter are complete. That is, you 
can type them, run them, and get a result. The procedures let 
you see the syntax and form of a command, as well as showing 
you how it might be used in a program. 


Because the programs are executable, the manual shows unfor- 
matted listings (without relative address, indented control struc- 
tures, and so on). This helps eliminate confusion for you when 
you type the program. You can type it exactly as it appears, exit 
the editor, and run the procedure. 
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ABS Return absolute value 


Syntax: ABS(number) 


Function: Computes the absolute value of number. A number’s 
absolute value is its magnitude without regard to its sign. 
Absolute values are always positive or zero. 


Parameters: 


number Any positive or negative number. 


Examples: 
PRINT ABS(-66) 


X=ABSCY) 


Sample Program: 


The following procedure asks you to type the temperature, and 
makes an appropriate comment. It uses ABS to get the absolute 
value of the temperature. 


PROCEDURE temperature 

DIM FEMPe INTEGER 

OINPUT “What’s the temperature outside? CDegrees 
Pisa Ss Lee 

OIF TEMP<@ THEN 


OPRINT "That’s '; ABSCTEMP); " below 
zero!'({LUBrrrrrrr!" 

JEND 

DENDIF 


DIF TEMP=@ THEN 

PRINT "Zero degrees? That’s mighty cold!” 

HEND 

WENDIF 

OPRINT TEMP; ™" degrees above zero? That’s kind of 
balmy...” 

WIEND 
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ACS Return arccosine 


Syntax: ACS(number) 


Function: Calculates the arccosine of number. Use the DEG or 
RAD commands to tell BASICO9 if number is in degrees or 
radians. If you do not specify degrees or radians, the default 
is radians. 


Parameters: 
number The number for which you want to compute 
the arccosine. 
Examples: 


PRINT ASCC.6561) 


Sample Program: 


The procedure calculates the arccosine of a value you type and 
expresses the result in degrees. 


PROCEDURE arccosine 

UDEG 

UDIM NUM:REAL 

JINPUT “Enter a number between -1 and 1",NUM 
HPRINT “The arecosite of “s NUM: ™” is=<="s3 
ACSCNUM) 

HEND 
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ADDR Return the location of a variable 


Syntax: ADDR(name) 


Function: Returns the absolute location in a process’s address 
space of the variable, array, or data structure assigned to 
name. The address returned is that of the first character in 
the variable. If the variable is numeric, one or more of the 
locations might contain zero. 


For instance, if you use ADDR to obtain the address of an 
integer variable that contains the value 44, the first address 
location (byte) contains 0, and the second location contains 44. 


Parameters: 
name The name of a string, a numeric variable, an 
array, or a data structure. 
Examples: 


This procedure displays the memory address where a variable 
named X resides: 


PRINT ADDRCX) 
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Sample Program: 


> This procedure uses ADDR to tell you the memory location of 
| the variable that stores your keyboard entry. 


PROCEDURE address 

UDIM A: INTEGER 

UTM TESTsSTRING 

WINPUT. “Type. 2: airing of chearacterscys' TEST 
UA=ADDRCTEST) 

PRINT “The string you typed is stored at address 
tt ray 

UPRINT “This is whet 1% eonteing?...™ 

FOR T=A TO A+LENCTEST) 

UPRINT CHRSCPEEKCT 22: 

UNEXT T 


UPRINT 
UEND 
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AND Performs a logical AND operation 


Syntax: operand1 AND operand2 


Function: Performs the logical AND operation on two or more 
values, returning a value of either TRUE or FALSE. 


Parameters: 
operand Can be either numeric or string values. 
operand2 

Examples: 
PRINT A>3 AND B>3 


PRINT AS="YES™" AND B$="YES" 


Sample Program: 


The following program calculates an insurance premium rate 
that is based on the answers to some lifestyle questions. Every 
time you press (Y}, the premium rate goes up. The procedure 
uses AND to increase the rate by two percent if you both smoke 
and drink. 


PROCEDURE policy 

DIM POLICY_VALUE,RATE:REAL 
ODIM SMOKE,DRINK:STRING[1] 
OPOLICY_VALUE=1000000. 


URATE=.001 
UENPUT “Doe you smoke? CY¥/ND...°, SMOKE 
OINPUT "Do you drink? CY/N)...",DRINK 


OIF SMOKE=""Y" AND DRINK#="Y¥" THEN RATE#RATE+. 92 
ELSE 

UIE SMOKE="Y¥" “THEN ‘RATE=KRATE?.81 

UENDIF 

DIF DRINK="Y¥" THEN RATE#RATE+. @1 

ENDIF 

JEN DEE 

UPRONT “Your premium 28 "s KATE*PUL ICY VALUE 
END 
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ASC Returns ASCIT code 


Syntax: ASC(string) 


Function: Returns the ASCII code for the first character of 
string. 


ASC returns the value as a decimal number. If string is null 
(contains no characters) BASICO9 returns Error 67 (Illegal 
Argument). 


Parameters: 


string Any string type variable or constant. 


Examples: 
PRINT ASCC"Hello') 


X = ASCCA$) 


Sample Program: 


The following procedure determines whether the first character 
you enter is a hexadecimal digit. To do this, it gets the ASCII 
value of the character and compares it to the ranges for charac- 
ters between 1 and 0 and A and F. 


PROCEDURE hexcheck 
UDIM A: INTEGER 
UDIM HEXNUM:STRING 


UILOOP 
OINPUT “Enter a hexadecimal value...',HEXNUM 
UJA=ASCCHEXNUM) \ C* GET THE ASCLI. CODE -*) 


DEXITIF A<48 OR A>S7 AND A<GS OR AX7B THEN 
OPRINT “Not a hex number." 

DEND 

DENDEXIT 
PRINT “es” 
HENDLOOP 


UJEND 
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ASN Returns arcsine 


Syntax: ASN(number) 


Function: Calculates the arcsine of number. ASN expresses its 
result in radians unless you specify otherwise (see DEG). 


Parameters: 
number The number for which you want to calculate 
the arcsine. 
Examples: 


PRINT ASCC.6561) 


Sample Program: 


The following program calculates the arcsine of a number you 
enter and expresses the result in degrees. 


PROCEDURE arcsine 


UDIM NUM:REAL 

UDEG 

UINPUT “Enter a number (€-1 to 1) ",NUM 

UPRINT “The arcsine of a ™s NUM; " is---": 
ASNCNUM) 

UEND 


11-10 


wo 


BASIC0O9 Command Reference / 11 


ATN Returns arctangent 


Syntax: ATN(number) 


Function: Calculates the arctangent of number. 


Parameters: 
number The number for which you want to find the 
arctangent. 
Examples: 


PRINT ASCC.6561) 


Sample Program: 


This procedure calculates arcsine, arccosine, and arctangent for 
a value you enter. 


PSOUCEDURE anglecale 

UIDIM NUM:REAL 

LIDEG 

OINPUT “Enter a number '",NUM 

UPRINT 

He oN 7a APCS Ne 4 Areeosi ne”, "Are tangent” 
LPRINT "Number, "Degreass™, “Degrees” ,;"Degrees” 

LP ROL (ORS ie ero ie oie ee See a eee eee em 
HIF NUM>1 OR NUM<-1 THEN 

HPRINT NUM,"UNDEF","UNDEF',ATNCNUM) 
UPRINT 

WEND 

ENDIF 

UPRINT NUM,ASNCNUM) ,ACSCNUM) ,ATNCNUM) 
UPRINT 

UEND 
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BASE Set array base 


Syntax: BASE 0 
BASE 1 


Function: Sets a procedure’s lowest array or data structure 
index to either 0 or 1. If you want to have the first elements in 
arrays set to 0, you must include BASE @ at the beginning of 
the procedure. 


The BASE statement does not affect string operations such as 
MID$, RIGHT$, and LEFT$. BASICO9 always indexes the 
first character of a string as 1. 


Parameters: 
0 or 1 If you do not indicate a BASE setting in a pro- 
cedure, BASICO9 uses a default of 1. 
Examples: 
BASE @ 


Sample Program: 


This procedure determines how many times RND selects each 
number between 0 and 11 out of 1000 selections. It stores the 
results in an array of 12 elements. Because it specifies BASE 0, 
one of the elements in the array is 0. Whenever the procedure 
picks a random number, it increments the value in the corre- 
sponding array number by one. 


PROCEDURE randomtest 
CIBASE @ (+ set the array base at 0. 
CIDIM RND_ARRAY(12),X,R: INTEGER (* dimension array to hold results. 


CIFOR X=@ TO 11 

LIRND__ARRAY(X)=@ (+ initialize array elements at zero. 
LINEXT X 

CISHELL "TMODE -PAUSE" (+ turn off screen pause. 

CIFOR X=1 TO 1000 


CR=RND(11) (* select random number 1000 times, 


11-12 


BASICO09 Command Reference / 11 


CIRND__ARRAY(R)=RND__ARRAY(R) +1 
(+ add 1 to appropriate element. 


CIPRINT 1001-X (+ count down from 1000 to 1. 
LINEXT X 

CIFOR X= TO 11 

LIPRINT "RND selected "; X; " "+ RND__ARRAY(X); " 

Limes." (#display array 

LINEXT X 

CISHELL "TMODE PAUSE" (* turn scroll lock back on. 
CIEND 
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BYE End procedure, terminate BASIC09 


Syntax: BYE 


Function: Ends execution of a procedure and terminates 
BASICO9. The statement closes any open files, but you lose 
any unsaved procedures or data. 


Use BYE to exit packed programs that you call from OS-9 and 
especially programs that you call from procedure files. 


Parameters: None 


Examples: 


INPUT "Press ENTER to return to the system." 3Z2$ 
BYE 


Sample Program: 


This procedure calculates the payments and interest of a loan. 
When it is through, it exits the procedure and BASICO9 with a 
BYE statement. 


PROCEDURE loan 

UIDIM PRIN,LENG,RATE,MONPAY:REAL 
LIDIM RESPONSE: STRING[1] 

LIREPEAT 

LIPRINT "Amortization Program" 

UINPUT "How much do you want to borrow?...",PRIN 
OINPUT “For how many months?...",LENG 

CKINPUT "At what interest rate?...",RATE 
HIA=RATE/1200 . 

LIB=1-1/€1+A)*LENG 

LIMONPAY=PRIN*A/B 

UIMONPAY=INTCMONPAY*100+.5)/100 

LIPRINT “Monthly payments are...$"; 

UIPRINT USING "R12.2<", MONPAY 

LIPRINT "The total interest to pay is...$"3 

LIPRINT USING "r12.2<", MONPAY*LENG-PRIN 

LIPRINT 

UINPUT "Do another calculation?...',RESPONSE 

LIPRINT 

LIPRINT 

UIUNTIL RESPONSE<>"y" 

LIBYE 

UIEND 

a cate ce a aS 5 
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CHAIN Execute another module 


ras 
Syntax: CHAIN “module [parameters|(...)” 


Function: CHAIN performs an OS-9 chain operation, passing 
module as the name of a program to execute. If you include 
other parameters, CHAIN passes them to the executing mod- 
ule. The module must be programmed to expect parameters of 
the type you provide. 


CHAIN exits BASICO9, unlinks BASICO9, and returns the 
freed memory to OS-9. 


CHAIN can begin execution of any module, not only BASICO9 
modules. It executes the module indirectly through the shell 
in order to take advantage of the shell’s parameter processing. 
This has the side effect of leaving the initiated shells active. 
Programs that repeatedly chain to each other eventually fill 

- memory with waiting shells. To prevent this, use the EX 
option to initialize a shell. 


BASICO9 does not close files that are open when you execute 
CHAIN. However, the OS-9 FORK call passes only the stan- 
dard I/O paths (0, 1, and 2) to a child process. Therefore, if 
you need to pass an open path to another program segment, 
use the EX shell option. 


Parameters: 
module The name of the procedure module you want 
BASICO9 to execute. 
parameters String data passed to the chained module. 
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Examples: 
CHAIN "ex BASIC@S menu" 


CHAIN "BASIC@9 #180k sort C""datafile™", 
"'tempf i letetyt 


CHAIN "DIR /DO" 


CHAIN "Dir; Echo *** Copying Directory #44; ex 
basic@9 copydir" 


Sample Program: 


This procedure chains to two others to display a directory or a 
file. It uses CHAIN to call the procedures. 


PROCEDURE chaining 

LIDIM RESPONSE: BYTE 

LIPRINT USING "S26*","- MENU -" (* print menu title. 

LIPRINT 

DIPRINT "1. List current data directory" (* print menu. 

DPRINT "2. Display a file" 

OPRINT "3. Exit to system" 

LIPRINT 

LIINPUT "Select a function (1-3) ",RESPONSE (+# function you want. 
LION RESPONSE GOTO 100,200,300 (* select appropriate function. 
1BBUCHAIN "EX BASIC@9 dirlook" (* chain to list directory. 
COBUCHAIN "EX BASIC@9 display" (*# chain to list file. 

300LIBYE 


PROCEDURE dirlook 
OREM Lists the specified directory 


LISHELL. “DERY (* execute dir command. 
CICHAIN “EX BASICA9 chaining" (# chain back to calling proc. 
LIEND 


PROCEDURE display 
OREM Lists the specified file. 


UDIM <F-LEEs JOB4S TRING 

INPUT “Path of tile to -displays.<* FILE 

[WOB="LiSt “*FILE 

OSHELL JOB (+ list specified file. 

LICHAIN “EX BASIC@9 chaining" (# chain back to calling proc. 
LIEND 
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CHD Change data directory 
CHX Change execution directory 


Syntax: CHD dirpath 
CHX dirpath 


Function: Changes the current data or execution directory. 


Parameters: 


dirpath An existing data or execution directory. 


Examples: 
CHD "/D1/ACCOUNTS/RECEIVABLE"™ 
CHX "/D1/CMDS" 
CHD: fs 


Sample Program: 


This procedure creates a directory, and makes it the data direc- 
tory. Then, it creates a file in the new directory, exits the new 
directory, and deletes the file and the directory. 


PROCEDURE chdtest 

LIDIM PATH: BYTE 

LISHELL "MAKDIR TEST" (+* create new directory named TEST. 
LICHD "TEST" (+ make TEST the data directory. 


LICREATE #PATH,"Samplefile":WRITE (* create a file in TEST. 
CREM Write data into the new file 

CIWRITE #PATH,"This file is for testing only." 

CIWRITE #PATH,"It will be destroyed when this procedure ends." 


UICLOSE #PATH 


LISHELL "LIST samplefile™ (# list the new file. 

GRD: Sey (+ make the ROOT the data directory, 
PISHELL "DEL TEST/samplefile" (+ delete the file. 

LISHELL “DELDIR TEST" (+ delete the directory. 

DIEND 
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CHRS$ Return ASCII character 


Syntax: CHRS$(code) wd 


Function: Returns the ASCII character for the value of code. 
CHR$ is the inverse of the ASC function, which returns the 
ASCII code for a given character. For a complete listing of 
ASCII codes, see Chapter 9. 


Parameters: 
code The ASCII value for a keyboard character or 
special block graphics character. 
Examples: 


PRINT CHR$C€88) 


Sample Program: 


By increasing by one the ASCII values of characters you type, a | 
the following program creates a secret code. It uses CHR$ to dis- 
play the secret code. 


PROCEDURE secret 

CIDIM TEXT, SECRETLINE:STRING(80] 
UIDIM T,CODECHAR: INTEGER 
LITEXT="" 

LISECRETLINE="" 


LIPRINT "Type a line to code in capital letters..." 

DUINPUT TEXT (+ you type a line. 

CIFOR T=1 TO LENCTEXT) 

LICODECHAR=ASC(MIDSCTEXT,T,1)) (* look at each character in line. 


CIIF CODECHAR=90 THEN (+ is it "2"? Tf yes then 

ICODECHAR=64 (# make it one less than "A", 

LIENDIF 

LIIF CODECHAR=32 THEN (+ is character a space? If yes then 

CICODECHAR=31 (+ decrease its value by one. 

MENDIF Lg 
PISECRETLINE=SECRETLINE+CHRS(CODECHAR+1) (# add 1 to characters. 

CINEXT T 

DIPRINT SECRETLINE (+ print the secret code. 

LIEND 


enn nnn nnn nnn nnn nnn nnnncnnnnececrecceeeeeeeeeeeeereeeeeeeeeeee cee SSS 
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CHX Change execution directory 
CHD Change data directory 


Syntax: CHX dirpath 
CHD dirpath 


Function: Changes the current execution or data directory. 


Parameters: 


dirpath An existing execution or data directory. 


Examples: 
CHX "/D1/CMDS" 
CHD "/D1/ACCOUNTS/RECEIVABLE" 
CHE st. 3™ 
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CLOSE Deallocate file or device path 


Syntax: CLOSE #pathnum 


Function: Deallocates the file or device path specified by 
pathnum. 


When you OPEN or CREATE a file, BASICO9 allocates a path 
number to the variable you supply in the OPEN or CREATE 
command. The system then knows the path by that number. If 
the path you CLOSE is to a non-shareable device (such as a 
printer), the system releases the device for other use. Do not 
close paths 0, 1, and 2 (the standard I/O paths) unless you 
immediately open a new path to take over the standard path 
number. 


Parameters: 
pathnum The name of variable containing the path 
number or the actual number of the path to a 
file or device. 
Examples: 


CLOSE #FILEPATH, #PRINTERPATH, #TERMPATH 

CLOSE #5, #6, #7 

CLOSE #1 \ (* closes the standard output path *) 

OPEN #PATH,"/T1" \ (# redirects standard output *) 
Sample Program: 


This procedure creates a directory named TEST and changes it 
to the data directory. It then creates a file named Samplefile and 
writes data to the file. Finally it changes back to the parent 
directory and deletes Samplefile and TEST. 
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PROCEDURE close 
LIDIM PATH: BYTE 
LISHELL "MAKDIR TEST" 


GERD FEST" 
LICREATE #PATH,"samplefile":WRITE (* create a new file. 

LINRITE #PATH,"This file is for testing only." 

CIWRITE #PATH, "It will be destroyed when this procedure ends." 
LICLOSE #PATH (# close the file. 

LISHELL "LIST samplefile™ 

PC aa 
LISHELL: “DELDIR TEST" 
LIEND 
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COS Return cosine 


Syntax: COS(number) 


Function: Calculates the cosine of number. Unless you specify 
DEG, COS interprets the value of number in radians. 


Parameters: 
number The number for which you want to find the 
cosine. 
Examples: 


PRINT COSC45) 


Sample Program: 


This procedure calculates sine, cosine, and tangent of a value 
you enter. 


PROCEDURE ratiocalc 


UDIM NUM:REAL 

LIDEG 

HINPUT "Enter a@ némber... "NUM 

UPRINT 

UPRENT “Namber“SINE’."“COSTNE™." TAN" 

LIPRINT "<<-<9 2-329 <2 ene ee ee eee eee eee eee rece es 


UPRINT ANGLE,SINCNUM) ,COSCNUM) , TANCNUM) 
UPRINT 
UEND 
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CREATE Establish a disk file. 


cr» 

Syntax: 

CREATE # path,“ pathlist’ [access mode] 

[+ access mode][ +...] 

Function: Creates a file on a disk. When you create a file, you 
can select one or more of the following access modes for the 
file: 

Mode Function 

READ Lets you read (receive) data from a file but 

does not let you write (send) data to the file. 

WRITE Lets you write data to a file but does not let 

you read data from a file. 

UPDATE Lets you both read from and write to a file. 

a 

Parameters: 
path The name of the variable in which BASICO9 

stores the number of the opened path. 

pathlist The route to the file or device to be opened, 

including the filename, if appropriate. 

access mode ‘The type of access to be allowed for the file or 

device. Use plus symbols to allow more than 
one type of access with a single file. 

Notes: 

@ You can access files either sequentially or randomly. With 
random access, you must establish the filing system you 
want for a particular application. 

~~ @ Files are byte-addressed, and you are not restricted by 


explicit record lengths. You can read the data one byte at a 
time, or in whatever size portions you want. 
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e A new file has a size of zero. OS-9 then expands the file 
automatically when PRINT, WRITE, or PUT statements 
write beyond the current end-of-file. 


Examples: 
CREATE #TRANS,"transportation":UPDATE 
CREATE #SPOOL,"/user4/report™: WRITE 


CREATE #OUTPATH,name$:UPDATE+EXEC 


Sample Program: 


This procedure CREATEs a directory named TEST and makes it 
the data directory. It creates a file in TEST named Samplefile, 
writes data to the file, then resets the parent directory as the 
data directory. Finally, it deletes Samplefile and TEST. 


PROCEDURE close 

CIDIM PATH:BYTE 

LISHELL "MAKDIR TEST" 

LICHD “TEST 

CICREATE #PATH,"samplefile":WRITE (* create a file. 
CWRITE #PATH,"This file is for testing purposes only." 
CWRITE #PATH,"It will be destroyed when this procedure ends." 
CICLOSE #PATH (# close the file. 

CISHELL "LIST samplefile™ 

CGH ge 

LISHELL "DELDIR TEST" 

LIEND 
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DATA Store numeric and string information 


Syntax: DATA “item”|[,“item’’,...] 


Function: Stores numeric and string constants to be accessed 
by a READ statement. A DATA line can contain up to 254 
characters. Each item in the list must be separated by 
commas. 


You can place DATA statements anywhere in a procedure that 
is convenient. BASICO9 reads sequentially, starting with the 
first item in the first DATA statement, and ending with the 
last item in the last DATA statement. 


The following rules apply to data items: 
@ You must place all string data between quotation marks. 


@ To include quotes in string-type data, use consecutive 
-_ quotation marks, like this: DATA "He said, ""go 
rome" “Lo me . 


@ You can use RESTORE to reset the data pointer. Using 
RESTORE without an argument resets the pointer to the 
beginning of the data items. Using RESTORE with a 
line number, resets the pointer to the first item in the 
specified line. 


@ The READ statement can support a list of one or more 
variable names of various types. The data types in DATA 
statements must match the variable types used in the 
corresponding READ statements. 


@ You can include arithmetic expressions in data items. 
READ causes the expressions to be evaluated and 
returns the result of the expression as the data item. 


Parameters: 
co” 


item Numeric or string characters. Enclose string 
characters in quotation marks. 
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Examples: 
DATA 1.1,1.5,9999,"CAT", "DOG" 
DATA SINCTEMP/25), COSCTEMP*PI) 
DATA TRUE,FALSE,TRUE,TRUE,FALSE 


DATA “The rain in spain’, "Ttalls mainly on the 
plain 


Sample Program: 


This procedure calculates the day of the week for a date you 


enter. A data statement contains the names of the weekdays. 


PROCEDURE weekday 
UDIM X,DAY,MONTH,YEAR,CALC: INTEGER 


INTEGER 
ODIM WEEKDAYC7):STRING[9] 

DPRINT USING “S60*", “Day of the Week Program” 
PRINT. USING *S60*™. "Por eny year atier T7se” 


UPRINT 


as 98...",DAY 

INPUT “Enter month as two digits, such «as 
Loewe ORT A 

LIAPUT “Enter year as Tour digits, siten 4s 
TBS S suas VER 

LUFOR 421 TO 7 

UREAD WEEKDAYCX) 

LINEXT xX 

DANUM=INTC.6+1/MONTH) 
UBNUM=YEAR-ANUM 
LICNUM=MONTH+12*ANUM 
UIDNUM=BNUM/1 09 
UENUM=INTCDNUM/ 4) 
UFNUM=INTCDNUM) 
NIGNUM=INTC5*BNUM/ 4) 
UHNUM=INTC13*CCNUM+1)/5) 

UC INUM=HNUM+GNUM-FNUM+ENUM+DAY -1 
UINUM=INUM-7* INTCINUM/7)+1 


UIPRINT 

UPRINT. *The day of ‘the week on "3. DAY: "7" MONTHS 
UPRENT “/"*s. YEARS ™- aeun oe WEEKDAYCINUMD 

JDATA "Sunday", "Monday", "Tuesday", "Wednesday", 
“Thwesdeay' 

UDATA “Friday”; “Saturday” 

HEND 
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DATES$ Provide date and time 


oe” 
Syntax: DATE$ 


Function: Returns the date and time. The OS-9 internal date 
is kept in the format: 


year/month/day hour:minutes:seconds 


If your OS-9 Startup file contains the SETIME command, the 
system asks you to enter the date and time whenever it boots. 
If it does not contain the SETIME command, the date and 
time start from 86/09/01:00:00:00. 


You can use the normal string functions to access the data 
contained in DATE$, but you cannot use functions or opera- 
tions that attempt to change or append to its values. To reset 
the date or time or both, use the SHELL command, such as: 


- SHELL "SETIME" 
Parameters: None 


Examples: 


PRINT DATE$ 


Sample Program: 


This program is essentially the same as the sample program for 
the DATA statement, except that it gets the day, month, and 
year from DATES. 


PROCEDURE date 

LIDIM X,DAY,MONTH, YEAR, CALC: INTEGER 

LIDIM ANUM,BNUM,CNUM,DNUM,ENUM,FNUM,GNUM,HNUM, INUM: INTEGER 
LIDIM WEEKDAY(7):STRING(9] 

a LIMONTH=VALCMIDSCDATE$ ,4,2)) (* get month from DATES. 
LIDAY=VAL(MIDSCDATE$,7,2)) (# get day from DATES, 
LYEAR=VALC"19"+LEFTS(DATE$ ,2)) (+ get year from DATES. 


LIFOR X=1 707 
UREAD WEEKDAY(X) 
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LINEXT X 
DIANUM=INTC.6+1/MONTH) 
LIBNUM=YEAR-ANUM 
LICNUM=MONTH+12#ANUM 
LIDNUM=BNUM/ 1 08 
DENUM=INTCDNUM/4) 
LIFNUM=INTCDNUM) 
LIGNUM=INT(S#BNUM/4) 
CHNUM=INTC13*(CNUM+1)/5) 
OINUM=HNUM+GNUM-FNUM+ENUM+DAY -1 
CINUM=INUM-7*#INTCINUM/7)+1 
LIPRINT 

DIPRINT "Today is "; WEEKDAYCINUM) 


LIDATA "Sunday","Monday", "Tuesday", "Wednesday", "Thursday", "Friday" 
LIDATA "Saturday" 
LIEND 
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DEG Return trigonometric calculations in 


degrees 


Syntax: DEG 


Function: Causes a procedure to calculate trigonometric val- 


ues in degrees. If you do not include the DEG statement, pro- 
cedures produce radian values. 


Parameters: None 


Examples: 


DEG 


Sample Program: 


This procedure calculates the sine, cosine, and tangent for a 
value you enter. Because it uses the DEG statement, it displays 
the results in degrees. 


PROCEDURE degcalec 


UDIM NUM:REAL 

ODEG 

UINPUT “Enter a number...',NUM 

UP RINT 

UPRINT “Number”. “SINE. "COSINE," TAN® 

OPRINT toro reev eee ee ecees eco oun eeeesedes 


JPRINT NUM,SINCNUM) ,COSCNUM) , TANCNUM) 
UPRINT 
UEND 
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DE LETE Erase a disk file 


Syntax: DELETE “pathname” 


Function: DELETE removes a file from disk storage and 
releases the portion of the disk on which it resides. When you 
DELETE a file, it is permanently lost. 


Parameters: 
pathname The complete pathlist to the file you want to 
delete, including the drive and one or more 
directories, if appropriate. You must surround 
the pathlist with quotation marks. 
Examples: 


DELETE “ryt iie” 


DELETE. "/D1/ACCOUNTS/receivables” 


Sample Program: 


This procedure creates a file named Samplefile, writes data to 
the file, then closes it. It then lists the file before deleting it. 


PROCEDURE close 

DDIM PATH: BYTE 

CICREATE #PATH,"samplefile":WRITE (+* create a file. 

CWRITE #PATH,"This file is for testing purposes only." 
DWRITE #PATH,"It will be destroyed when this procedure ends," 
LICLOSE #PATH (# close the file. 

LISHELL "LIST samplefile™ 

KIDELETE "samplefile" 

LIEND 
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DIM Assign variable storage 


Syntax: DIM variablel....][:typell;variablelf,...]I: typell...] 


Function: Assigns storage space and declares types for vari- 
ables, arrays, or complex data structures. 


Parameters: 
variable A simple variable, an array structure, or a 
complex data structure. 
type BYTE, INTEGER, REAL, BOOLEAN, 
STRING, or user defined. 
Notes: 


@ You declare simple arrays with DIM by using the variable 
name, without a subscript. If you do not explicitly declare 
variables, the system makes them type real unless they are 
followed by a dollar sign ($). The system dimensions vari- 
ables ending with a dollar sign ($) as strings, with a length 
of 32 bytes. You must declare types of all other simple vari- 
ables as to type. 


@ You can declare several variables of the same type by sepa- 
rating them with commas. To separate variables of differ- 
ent types, follow each type group with a colon, the type 
name, and then a semicolon. 


@ Define a maximum length for a string variable by enclosing 
the length in brackets following the type, like this: 


DIM namesstringl2s] 
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If you do not define a maximum length, BASICO9 uses a 
default length of 32 characters. You can declare a shorter 
length or a longer length, up to the capacity of BASICO9’s 
memory. If you try to extend a string beyond its declared 
length, or beyond the default length, the system ignores all 
extra characters. Thus the following: 


DIM name:string[10] 
name = "Abbernathinsky" 


produces the string: 


Abbernathi 

e Arrays can have one, two, or three dimensions. The DIM 
format for dimensioned arrays is the same as for simple 
variables, except that you must follow each array name 
with a subscript, enclosed in parentheses, to indicate its 
size. The maximum array size is 32767. 
Arrays can be either of the standard BASICO9 type or of a 
user-defined type. For information on creating your own 
types for simple variables, arrays, and complex data struc- 
tures, see TYPE. 

Examples: 

DIM logical:BOOLEAN 

DIM 84. bate INTEGER 

DIM name,address,zip:STRING 

DIM name:STRINGL25]; address:STRING( 30]; 

Zioe INTEGER 

DIM no1,n02,n03:REAL;n04,n05,n06: INTEGER; 

nmo7sBYTE 
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Sample Program: 


This procedure randomly selects letters and vowels to create six- 
letter words that might look like alien names. It first DIMs nine 
string variables to contain the letters selected for each name. It 
DIMs two integer variables to provide a loop counter and to store 
the number of names you request. 


When asked, type the number of names you want to have the 
procedure generate. 


PROCEDURE alien 

UDIM B,BEGIN,F,FINISH: STRING 
UDIM VOWELS ,VOWEL1 ,VOWEL2:STRING 
UDIM MID1,MID2:STRING 

UDIM T,RESPONSE: INTEGER 
LIIVOWELS=""aeiouy™ 


UINPUT "How many alien names do you want to 
see?...™", RESPONSE 
UBEGIN="ABCDFGHJKLMNPRSTVWXZ" 

UF INISH="ehimnprstvwyz" 


FOR T=1 TO RESPONSE 
UB=MID$CBEGIN,RNDC19)+1,1) 

UF =MID$CFINISH,RNDC12)+1,1) 
UMID1=CHR$CRNDC25)+97) 
UMID2=CHR$CRNDC25)+97) 
UVOWEL1=MID$CVOWELS,RNDC5)+1,1) 
UVOWEL2=MID$CVOWELS ,RNDC5)+1,1) 

UPRINT B; VOWEL1; MID1; MID2; VOWEL2; F, 
FINEST F 


UPRINT 
END 
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DO Execute procedure lines in a loop 


Syntax: WHILE expression DO 
proclines 
ENDWHILE 


Function: Establishes a loop that executes the procedure lines 
between DO and ENDWHILE as long as the result of the 
expression following WHILE is true. Because the loop is 
tested at the top, the lines within the loop are never executed 
unless expression is true. 


Parameters: 
expression A Boolean expression (produces a result of 
True or False). 
proclines Are program lines to execute if the expression 


is true. 


See WHILE/DO/ENDWHILE for more information. 
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ELSE Execute alternate action 


Syntax: IF condition THEN 
action 
ELSE 
secondary action 
ENDIF 


Function: ELSE provides access to a secondary action within 
an IF/THEN test. When the condition tested by IF is not 
true, BASICO9 executes the secondary action preceded by 
ELSE. 


Parameters: 

condition A Boolean expression (produces a result of 
True or False). 

action A line number to which the procedure is to 
transfer execution, or a program statement. If 
action is a line number, do not include the 
ENDIF statement in the IF test. 

secondary One or more program statements. 

action 


For more information, see IF/THEN/ELSE 
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END Terminate a procedure 


Syntax: END [“text’] 


Function: Ends procedure execution and returns to the calling 
procedure, or to the highest level procedure. If you provide 
output text for END, it functions in the same manner as 
PRINT. You can use END several times in the same proce- 
dure. END is not required as the last statement in a 
procedure. 


Parameters: 


text A literal string or a string-type variable. 


Examples: 
END "Program Terminated" 


LAST$="Session over" 
END LAST$ 


Sample Program: 


This procedure calculates a loan’s term, using END to termi- 
nate routines. 


PROCEDURE loaner 
ODIM YOUPAY,PRINCIPLE, INTEREST ,NUMPAY, YEARS, 


MONTHS:REAL 
ODIM. RESPONSE:STRING( 13 


OREPEAT 

UPRINT 

OPRINT USING "S45%","Loan Terms" 

PRINT 

GISPUT Amount of Regular Payments... ,YOUPAY 
Lae Enter the Prineiples«.",PRINGIPLE 
Lae, Enter the Annual Interest Rate...", 
INTEREST 

WES aro R Mie Enter the Number of Payments 

Year lyews™",NUMPAY 
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UYEARS=-CLOGC1-PRINCIPLE*CINTEREST/109@)/ 
CNUMPAY*YOUPAY))/CLOGC1+INTEREST/188/NUMPAY )* 
NUMPAY)) 

LIMONTH=INTCYEARS#12+.5) 

LYEARS=INTCMONTH/12) 


UMONTH=MONTH-YEARS#12 

PRINT ™ The Term of Your Loan is ™; YEARS; " 
years. and *s MONIES: * montis.” 

UINPUT "Calculate another or Quit (C/Q)?...", 
RESPONSE 


UUNTIL RESPONSE<>"C"™ AND RESPONSE <>!"c'! 
UDEND “Coodbye... I hope I helped you.” 
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ENDE XIT Leave loop if a condition is True 


Syntax: EXITIF condition THEN 
proclines 
ENDEXIT 


Function: ENDEXIT terminates an EXITIF test. You always 
use EXITIF/THEN/ENDEXIT inside a procedure loop. If the 
Boolean expression tested by EXITIF is true, BASICO9 exe- 
cutes the program statements between THEN and ENDEXIT 
and then transfers program operation outside the loop. If the 
condition tested by EXITIF is not true, loop execution contin- 
ues at the statement following ENDEXIT. 


Parameters: 
condition A comparison operation that returns either 
True or False, such as A=B, A<B, or 
A=B=C. 
proclines One or more statements to perform if the Boo- 


lean expression tested by EXITIF is True. 
For more information, see EXITIF/THEN/ENDEXIT 
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EN DIF Close IF statement 


Syntax: IF condition THEN 
action 
[ELSE 
secondary action] 
ENDIF 


Function: ENDIF terminates an IF/THEN condition test. If 
the condition tested by IF is true, BASICO9 executes the 
statements between THEN and ENDIF. If the condition tested 
by IF is not true, BASICO9 transfers execution to the proce- 
dure line following ENDIF or (optionally) executes the state- 
ments following ELSE. 


Parameters: 

condition A Boolean expression (produces a result of 
True or False). 

action A line number to which the procedure is to 
transfer execution. Action can also be a pro- 
gram statement. If action is a line number, do 
not include the ENDIF statement in the IF 
test. 

secondary A program statement. 

action 


For more information, see IF/THEN/ELSE/ENDIF. 
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ENDLOOP Close LOOP statement 


Syntax: LOOP 
statement(s) 
ENDLOOP 


Function: ENDLOOP terminates a procedure loop established 
by the LOOP command. BASICO9 endlessly executes all proce- 
dure statements between LOOP and ENDLOOP repeatedly 
unless a condition test within the loop (such as EXITIF’/ 
THEN/ENDEXIT, or IF/THEN) transfers execution outside of 
the loop. 


Parameters: 


statement(s) One or more procedure lines that execute 
within the loop. 


For more information, see LOOP/ENDLOOP. 
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ENDWHILE Close WHILE statement 


Syntax: WHILE condition DO 
proclines 
ENDWHILE 


Function: Forms the bottom of a WHILE loop. WHILE causes 
the procedure lines between DO and ENDWHILE to execute 
as long as the result of the expression following WHILE is 
true. Because the loop is tested at the top, the lines within 
the loop are never executed unless the expression is true. 


Parameters: 
condition A Boolean expression (produces results of True 
or False). 
proclines Are program lines to execute if the expression 
is true. 


For more information, see WHILE/DO/ENDWHILE. 
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EOF Test for end-of-file 


Syntax: EOF(path) 


Function: Tests for the end of a disk file. The function returns 
a value of True when it encounters an end-of-file; otherwise, it 
returns False. Use EOF with a READ or GET statement. 


Parameters: 
path The number of the path you are accessing. 
BASICO9 automatically stores a path number 
into the variable you specify during a 
CREATE or OPEN operation. 
Examples: 


IP EOP C#PATHS THEN 
CLOSE #PATH 
ENDIF 


Sample Program: 


This procedure redirects a listing of the current directory into a 
file named Dirfile. It then lists Dirfile to the screen. EOF tells 
the WHILE/ENDWHILE loop when the READ operation reaches 
the end of the file. 


PROCEDURE readfile 

UDIM A:STRING[88@] 

DIM PATH: BYTE 

NSHELE "DIR > dirtile™ 
JOPEN #PATH,"dirfile'™:READ 
UWHILE NOT EOFC#PATH) DO 
UJREAD #PATH,A 

UIPRINT A 

UENDWHILE 

CLOSE #PATH 

UEND 
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ERR Return error code 


Syntax: ERR 


Function: Returns the error code of the most recent error. 
BASICO9 automatically sets the ERR code to zero after you 
reference it. ERR is only useful when used in conjunction with 
BASICO9’s ON ERROR error trapping functions. 


See Appendix A for a list of all BASICO9 error codes. 
Parameters: None 


Examples: 


ERRNUM = ERR 

ITF ERRNUM = 218 THEN 

PRINT “File already exists. Please use another 
filename." 

ENDIF 


Sample Program: 


This procedure displays the contents of a file you select. If the 
file doesn’t exist (Error 216, Pathname not found), the procedure 
uses ERR to tell you. If an error other than Error 216 occurs, 
the procedure displays I can’t handle error xx, where xx is 
the code of the error. 
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PROCEDURE readfile 

CDIM READFILE:STRING; A:STRING(80]; PATH: BYTE 

1OLINPUT "Type the pathlist of the file to read...",READFILE 
HON ERROR GOTO 100 (* if an error occurs, skip to line 100. 
KIOPEN #PATH,READFILE:READ 

CWHILE EOFC#PATH)<>TRUE DO 

DREAD #PATH,A 

LIPRINT A 

LIENDWHILE 

KICLOSE #PATH 

LIEND 

{OOOERRNUMSERR (* store the error code in ERRNUM, 

DIF ERRNUM=216 THEN (* if file doesn’t exist say so. 

CIPRINT "I can’t find the file...Please try again." 

LION ERROR 

LIGOTO 18 

LIENDIF 


LICLOSE #PATH 


LIEND 
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ERROR Simulate an error 


Syntax: ERROR code 


Function: Simulates the error specified by code. You would 
mainly use this command to test ON ERROR GOTO routines. 
When BASICO09 encounters an ERROR statement, it proceeds 
as if the error corresponding to the specified code has 
occurred. Refer to Appendix A for a listing of error codes and 
their meanings. 


Parameters: 


code The code of the error you want to simulate. 
Examples: 


ERROR 207 

ERRNUM = ERR 

IF ERRNUM = 207 THEN 

PRINT “Memory is full. The current data is being 
saved to disk." 

ENDIF 


Sample Program: 


This program creates a file named Testl. Before creating the 
file, it checks to see if it already exists. If the file exists, the pro- 
cedure deletes it. An error trap catches any error that might 
occur. To test if the trap works for Error 216, “Pathname not 
found”, the statement ERROR 216 is inserted as the fourth line. 
After testing the trap to make sure it works, delete this line to 
use the procedure. 
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PROCEDURE errortest 


DIM PATH,ERRNUM: BYTE; RESPONSE:STRING[1] 
UBASE @ 

HON ERROR GOTO 19 (* set error trap 
DERROR 216 C* simulate error 
UIDELETE: “testi” 

GOTO 100 


19JERRNUM=ERR 

HIF ERRNUM=216 THEN 

OINPUT "File doesn’t exist...continue? 

CY/NO" ,RESPONSE 

HIF RESPONSE="N™ THEN 

HEND “Procedure terminated at your Pequest <i." 
WENDT F : 


LENDIF 

HON ERROR C* turn off error trap. 
199@UCREATE #PATH,"“testi":WRITE 

DEND 
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EXITIF/THEN/ENDEXIT 


Exit from loop if a condition is true 


Syntax: EXITIF condition THEN 
statement 
ENDEXIT 


Function: Use these statements with loop constructions (par- 
ticularly LOOP and ENDLOOP) to provide an exit for what is 
otherwise an endless loop. EXITIF performs a test of a Boo- 
lean expression, such as A<B. The THEN statement precedes 
any operation you want to execute if the expression is true. 
You must always follow EXITIF with an ENDEXIT. 


If the Boolean expression following an EXITIF is false, execu- 
tion of the program transfers to the statement immediately 
following the body of the loop (after the ENDEXIT statement). 
Otherwise, BASICO9 executes the statement(s) between 
EXITIF and ENDEXIT, then transfers control to the state- 
ment following the body of the loop. 


You can also use EXITIF and ENDEXIT with types of loop 
-constructions other than LOOP/ENDLOOP. 


Parameters: 
Boolean A comparison operation that returns either 
expression True or False, such as A=B, A<B, or 
A=B=C. 
statement An operation to be performed if the Boolean 


expression tested by EXITIF is True, such as: 
PRINT A is less than B. 
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Examples: 


Loe 

COUNT =COUNT +1 

EXITIF CUUNT>10@ THEN 
DUNE. ® “TRUE 

ENDEXIT 

PRINT COUNT 

X = COUNT/2 

ENDLOOP 


Sample Program: 


This procedure simulates a gambling machine by randomly 
selecting among several fruit names and displaying them. It 
gives you a starting stake of $25 and, depending on the combi- 
nation of fruit selected, it adds or subtracts from your stake. 


If your stake drops to zero, an EXITIF statement ends the proce- 
dure and tells you that you’re broke. 


PROCEDURE onearm 
DIM FRUIT1.FRUIT2, FRUITS, STAKE: INTEGERS FRUITCS): 
STRING[I6] 


USTAKE=25 
PRINT -\ PRINT “You have $3; STAKES ” to play 
WwEtha 


OFOR T=1 TO 8 

TREAD FRUITCT) 

NEXT T 

Loop 

OFRUIT1=RNDC7)+1. \FRUIT2=RNDC7)+1 \FRUIT3=RNDC7)+1 
OPRINT FRUITCFRUIT1); " "; FRUITCFRUIT2); " "; 
FRUITCFRUIT3) 

IF FRUITCFRUIT1)=FRUITCFRUIT2) AND FRUITCFRUIT1)= 
FRUITCFRUIT3) THEN STAKE=STAKE+10 

ELSE 

IF FRUITCFRUIT1)=FRUITCFRUIT2) OR FRUITCFRUIT1)= 
FRUITCFRUIT3) OR 

OF RUITCFRUIT2)=FRUITCFRUIT3) THEN 

TSTAKE=STAKE+1 

TELSE 

OSTAKE=STAKE-1 

JENDIF 

JENDIF 
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JREM exit play loop is stake is less than $1. 
NEXITIF STAKE<1 THEN 

OPRINT 

PRINT "You’re Busted...Better go home." 
DENDEXIT 

UPRINT “Your stake is now $"; STAKE; "," 
LIPRINT 

OPRINT 

UINPUT "Press ENTER to Ue Saal See es 
LENDLOOP 

DEND 

UDATA "ORANGE", "APPLE","CHERRY","LEMON'', "BANANA" 
UDATA "PEAR", "PLUM","PEACH" 
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EXP Return natural exponent 


Syntax: EXP(number) 


Function: Returns the natural exponent of number, that is, e 
(2.71828183) to the power of number. Number must be 
positive. 


This function is the inverse of the LOG function. Therefore, 
number = EXP(LOG(number)). 
Parameters: 


number A positive value. 


Examples: 


PRINT. EXPC2) 


Sample Program: 


This procedure calculates the exponent of values in the range 
0-1. 


PROCEDURE exprint 

FOR: T=2. To 1 STERP- .@3 

PRINT EXPCTI,EXPCT+, 8127 ,EXPCT+. 829 
ONEXT T 

LIEND 
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FALSE Assign Boolean value 


Syntax: variable=FALSE 


Function: FALSE is a Boolean function that always returns 
False. You can use FALSE and TRUE to assign values to Boo- 
lean variables. 


Parameters: None 


Examples: 


DIM TEST: BUOLEAN 
TEST#FALSE 


Sample Program: 


The procedure uses a Boolean variable to store True or False, 
depending on whether you answer some questions correctly or 
incorrectly. 


PROCEDURE quiz 

UDIM REPLY,VALUE:BOOLEAN; ANSWER:STRING[1]; 
QUESTION: STRING[8@] 

UFOR T=1 TO S 

UREAD QUESTION,VALUE 

UPRINT QUESTION 

UPRINT "CT) = TRUEQOOUDOUCF) = FALSE" 

BeRINT “Select. Tt or Fats 

LIGET #1,ANSWER 

UIF ANSWER="T" THEN 

HREPLY=TRUE 

TE oe 

UREPLY=FALSE 

HEND IF 

DIF REPLY=VALUE THEN 

UPRINT \ PRINT "That’s Correct...Good Show!" 
JELSE 

UPRINT “Sorry, you" re wrong...Better Luck next 
Lime.” 

ENDIF 

PRINT SPRINT ~\- PRINT 
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ONEXT T 
UDATA "In computer talk, CPU stands for Central 
Packaging Unit.", FALSE 


ODATA "The actual value of 64K is 65536 
bytes. , TRUE 

ODATA "The bits in a byte are normally numbered @ 
through 77%, TRUE 


ODATA "BASICO9 has four data types.",FALSE 
ODATA "The LAND function is a Boolean type 
operator.” ,FALSE 


HEND 
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F IX Round a real number 


Syntax: FIX(value) 


Function: Rounds a real number to the nearest whole number 
and converts it to an integer-type number. Fix performs a 
function that is the opposite of the FLOAT function. 


Parameters: 


value Any real number. 


Examples: 


A=RNDC1 0) 
PRINT FIXCA) 


Sample Program: 
This procedure displays the FIXed values of seven constants. 


PROCEDURE printfix 
OPRINT FIXG1 «23 
UPRINT: FF IXCT...39 
LIPRIANT -FEXCT 52 
HIPRINT FIX<€1.89 
UPRINT FIX€99.S566666) 
PRINT -FIRCS@.1) 
UPRINT FIXC.7654321) 
UIPRINT FIX€-12.44) 
UPRINT FIX€=9,99) 
NEND 
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FLOAT Convert from integer or byte to real 


Syntax: FLOAT(value) 


Function: Converts an integer- or byte-type value to real type. 
FLOAT performs a function that is the opposite of the FIX 
function. 


Parameters: 


value An integer- or byte-type number. 


Examples: 


DIM TEST: INTEGER 
TEST=44 
PRINT FLOATCTEST)/3 


Sample Program: 


This procedure uses FLOAT to produce a real number result of 
an inch to centimeter conversion. 


PROCEDURE convert 

ODIM T: INTEGER; MEASURE:STRING[11] 
OFOR T=1 TO 18 

OIF T=1 THEN 

COMEASURE="centimeter " 

HELSE 

OMEASURE="centimeters" 

DENDIF 

EPRINT Te“ s MEASURE: “ae “¢ FLOATCT)*.39873 


inches.” 
UNEXT T 
DEND 
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F OR/ NEXT/ STEP Establish a loop 


Syntax: 

FOR variable = init val TO end val [STEP value] 
[procedure statements] 

NEXT variable 


Function: Establishes a procedure loop that lets BASICO9 exe- 
cute one or more procedure statements a specified number of 
times. The variables you use can be either integer or real type 
and can be negative, positive, or both. Loops using integer 
values execute faster than loops using real values. 


BASICO9 executes the lines following the FOR statement until 
it encounters a NEXT statement. Then it either increases or 


decreases the initial value by one (the default) or by the value 
given STEP. 


Parameters: 
variable Any legal numeric variable name. 
init val Any numeric constant or variable. 
end val Any numeric constant or variable. 
value Any numeric constant or variable. 
procedure Procedure lines you want to be executed 
statements within the loop. 
Notes: 


e If you provide an initial value that is greater than the final 
value, BASICO9 skips the program loop entirely unless you 
specify a negative STEP value. Specifying a negative value 
for STEP causes the loop to decrement from the initial 
value to the end value. 
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@ When execution reaches the NEXT statement in a positive 
stepping loop, and the step value is less than or equal to 
the end value, BASICO9 branches back to the line after 
FOR and repeats the process. When the step value is 
greater than the end value, BASICO9 transfers execution to 
the statement following the NEXT statement. 


@ When execution reaches the NEXT statement in a negative 
stepping loop, and the step value is greater than or equal 
to the end value, BASICO9 branches back to the line after 
FOR and repeats the process. When the step value is less 
than the end value, execution continues following the NEXT 
statement. 


Examples: 


FOR COUNTER = 1 to 1808 STEP .5 
PRINT COUNTER 
NEXT COUNTER 


FOR X% = 18 TO 4 STEP --% 
PRINT X 
NEXT X 


FOR TEST = A TO B STEP ‘RATE 
PRINT TEST 
NEX?) TES! 


Sample Program: 


This procedure uses two nested FOR/NEXT loops to produce a 
multiplication table. 


PROCEDURE multable 
OPRINT USING "S45*","MULTIPLICATION TABLE" 
OPRINT 

ODIM I,J:INTEGER 

OFOR I=1 TO 9 

OFOR J=1 TO 9 

OIF J>1 THEN 

OPRINT I#J; TABCS*J); 
NELSE PRINT I*J; "| "3 
CENDIF 

ONEXT J 

OIF I=1 THEN 

OPRINT "" 


—— aaa acca 
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GET Read a direct-access file record 


Syntax: GET #path,varname 


Function: Reads a fixed-size binary data record from a file or 
device. Use GET to retrieve data from random access files. 


Although you usually use GET with files, you can also use it 
to receive data for any outputting device, such as a keyboard 
or another computer. By dimensioning a string variable to the 
length of input you want, you can use GET to read a specified 
number of keystrokes, then continue program execution with- 


out requiring [ENTER] to be pressed. 


For information about storing data in random access files, see 
Chapter 8, “Disk Files.” Also see PUT, SEEK, and SIZE. 


Parameters: 
path A variable name you choose in which BASICO9 
stores the number of the path it opens to the 
device you specify or one of the standard I/O 
paths (0, 1, or 2). 
varname The variable in which you want to store the 
data read by the GET statement. 
Examples: 


GET #PATH,DATAS 
GET #1,RESPONSES 


GET #INPUT,INDEXCX) 


Sample Program: 


This procedure directs a directory listing to a file named Dirfile. 
GET then reads the file, one character at a time in order to 
determine which characters are valid filename characters. The 
procedure creates a file containing all the filenames in the 
directory. 
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PROCEDURE filenames 

LIDIM DIRECTORY ,FILENAME:STRING; CHARACTER:STRING(1]; FILES(125):STRING(15]; 
PATH, COUNT, T: INTEGER 

LICOUNT=8 

LIFILENAME="" 

OFOR T=1 TO 125 (# initialize array elements to null, 

LIFILES(T)="" 

LINEXT T 

LIINPUT "Pathlist of directory to read...",DIRECTORY (# dir to copy. 
LION ERROR GOTO 18 

LIDELETE "dirfile" (* if dirfile already exists, delete it, 

1@LJON ERROR 

LISHELL "DIR "+DIRECTORY+" > dirfile" (* copy directory into file. 
LIOPEN #PATH,"dirfile":READ (+ open the file for reading. 

LIREPEAT 

LIREM Get characters from the file until the first carriage return - the 
beginning of the first filename. 

LIGET #PATH, CHARACTER (+ get characters from the file. 

LIUNTIL CHARACTER=CHR$(13) 

LIREM 

2@LLO0P 

LIEXITIF EQFC#PATH) THEN 

HGOTO 208 (* quit when end of file. 

LIENDEXIT 

LIREM get a character from the file until it finds a non-valid filename 
character, 

LIGET #PATH, CHARACTER 

LIREM 

LIEXITIF CHARACTER<="_" OR CHARACTER>"'z" THEN 

HGOTO 100 

LIENDEXIT 

LIFILENAME=FILENAME+CHARACTER (* build the filename. 

CIENDLOOP 

1OOLWHILE NOTCEQFC#PATH)) DO 

LIGET #PATH, CHARACTER (*-check for non-valid filename characters. 
LIEXITIF CHARACTER)" " AND CHARACTER<="z" THEN (* check if valid char. 
LICOUNT=COUNT+1 

LIFILESCCOUNT)=FILENAME (* store filename in array, 

LIPRINT FILENAME, (# display the extracted filename. 

LIFILENAME="" (# set variable to NULL. 

LIFILENAME=FILENAME+CHARACTER (* last character begins new filename. 
LIGOTO 20 (* go get the rest of filename. 

LIENDEXIT 

LIENDWHILE 

COOLICLOSE #PATH 
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ODELETE “dirfile" (* names are all in array so delete file. 
OCREATE #PATH,"dirfile":WRITE (# create the file again. 
DFOR T=1 TO COUNT 

CWRITE #PATH,FILES(T) (# fill the file with individual filenames. 
CNEXT T 

OICLOSE #PATH 

LIPRINT 

OPRINT "CUOOUO0 +The directory has "; COUNT; " entries” 
OPRINTO"OOOOO00oThey are now stored ina file named Dirfile." 
KIEND 
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GOSUB/RETURN 


Jump to subroutine/ Return from subroutine 


Syntax: GOSUB linenumber 


Function: Branches program execution to the specified line 


number. 


BASICO9 lets you write programs with line numbers or with- 
out. You can also mix numbered and un-numbered lines 
within a single procedure. This means that, to use GOSUB, 
you need to number only the first line of the subroutine to 
which you want to branch. 


Every subroutine you access with GOSUB must contain a 
RETURN statement. You can call a subroutine in this man- 
ner aS many times as you want. When BASICO9 encounters 
the RETURN, it transfers program execution to the line fol- 
lowing the GOSUB statement. 


You can precede GOSUB with a test statement, such as IF or 
WHEN, that makes branching conditional. 


You can nest GOSUB statements to any depth, depending on 
your computer’s free memory. 


Parameters: 
linenumber The number of the line where procedure exe- 
cution is to continue. 
Examples: 
GOSUB 1090 
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Sample Program: 


The following procedure asks you for two numbers and an opera- 
tor. It determines the line to jump to by the position of the oper- 
ator in a table. GOSUB sends the procedure to execute the 
proper routine. RETURN sends the execution back to the main 
routine. To quit, enter a negative value. 


PROCEDURE calc 

ODIM NUM1,NUM2:REAL; OP:STRING[11]; A: INTEGER 
1OINPUT "NUMBER 1 ‘*3;NUM1 
OIF NUM1<@ THEN 

UEND 

DENDIF 

DOINPUT "NUMBER 2 "sNUM2 
OINPUT “OPERATOR ™;O0P 
OA=SUBSTRCOP ,“"*+-#/*"") 

HOON A GOSUB 10,280,30,48,590 
UGOTO 1 


1@0PRINT NUM1+NUM2 \ RETURN 
2B0PRINT NUM1-NUM2 \ RETURN 
300PRINT NUM1*NUM2 \ RETURN 
4Q0PRINT NUM1/NUM2 \ RETURN 
SOOPRINT NUM1 NUM2 \ RETURN 


LEND 
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IF/THEN/ELSE/ENDIF 


Test a Boolean expression 


Syntax: IF condition THEN linenumber 
[ELSE 
secondary action 
ENDIF] 


IF condition THEN 
action 

[ELSE 

secondary action] 
ENDIF 


Function: Tests a Boolean expression and executes action if the 
expression is true. Optionally, the statements execute a sec- 
ondary action if the expression is not true. Each IF statement 
must be accompanied by THEN. If action is a line number, 
you can omit the ENDIF statement. For instance, both of the 
following statements operate in the same manner: 


IF T=S THEN 19 


IF T=S THEN 

GOTO 10 

ENDIF 

Parameters: 

condition A Boolean expression (produces True or False). 

linenumber A line to which the procedure is to transfer 
execution if condition is true. 

action One or more procedure statements to be exe- 
cuted if condition is true. 

secondary One or more procedure statements to execute 

action if condition is false. 
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Examples: 
IF A>B THEN 108 


IF A<B THEN 198 
EL or 

A=A-1 

ENDIF 


IF TEST=TRUE THEN 
PRINT "The test is a SUCCcCesS..."™ 
ENDIF 


IF A «< B THEN 

PRINT "A is less than B" 
Poe 

PRINT "B is less than A" 
ENDIF 


Sample Program: 


The following procedure is a purge procedure. Use it only with 
the GET Sample Program to delete one or more files from your 
current directory. 


The Filenames procedure (see GET) stores the current directo- 
ry’s filenames in Dirfile. This procedure reads Dirfile, displays 
all the filenames, then asks you for a wildcard. Type in charac- 
ters that identify a group of files you want to delete. The pro- 
gram deletes all files that contain, in the same order and case, 
the characters you type. 


For instance, if you have four files named Test, Filel, File2, and 
File3, and you type a wildcard of “File,” the procedure deletes 
Filel, File2, and File3, but does not delete Test. Delete all of the 
files in a directory by typing “*” as the wildcard. 


Use this program carefully. Be sure you are in the right 
directory and that the wildcard characters you type are not con- 
tained in filenames other than the ones you want to delete. You 
might want to add a prompt to the procedure that lets you con- 
firm each deletion before it happens. 
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PROCEDURE purge 

UDIM PATH: INTEGER 

UDIM NAMEC188):STRING 

UDIM WILDCARD:STRING 

X= 

JOPEN #PATH,"dirfile'™:READ 

UWHILE NOTCEOFC#PATH)) DO 

UX=X+1 

READ #PATH,NAMECX) 

NENDWHILE 

FOR T= TO xX 

UPRINT NAMECT), 

UINEXT T 

UINPUT "Wildcard Characters...™",WILDCARD 
UPGR T<? Ta -x 

WON ERROR GOTO 182 

UIF SUBSTRCWILDCARD,NAMECT))>@ OR WILDCARD=""*" 
THEN 

PRINT "DELETING “Ss (NAMECTI: “- coxvvar “ 
UDELETE NAMECT) 

LIENDIF 

1OUNEXT T 

WIEND 

1O@UPRINT "* * * ERROR * * * "; NAMECT): "™ cannot 
be deleted. ,continuing.,™ 

UGOTO 190 
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INKEY Read a keypress 


Syntax: RUN INKEY (string) 


Function: Reads a keypress, and stores the character of the 
key in the specified string variable. 


Parameters: 
string is a string variable into which INKEY stores 
the character you press. 
Examples: 
DIM CHAR:STRING[11] 
C a A a =— '008 
WHILE CHAR=""" DO 
RUN INKEYCCHAR) 
ENDWHILE 


PRINT ASCCCHAR) 
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Sample Program: 


PROCEDURE Calculate 

UDIM CHAR:STRING[1] 

UDIM LOOKUP:STRING[7] 

UDIM FIRST,SECOND: REAL 

UDIM FLAG: INTEGER 

DLOOKUP="+-*#/%<¢>" 

1 FLAG=@ \CHAR=""" 

UPRINT “Enter the first number to evaluate..."; 
UINPUT FIRST 

UIF FIRST=@ THEN 


UGOTO 100 
DENDIF 
UPRINT “Enter the second number to evaluate...":; 


UINPUT SECOND 

JPRINT “Press the key of the operator you want to 
UEesv.” 

EP RE Shae soe ae he A ARE a 
UWHILE CHAR="" DQ 

RUN INKEYCCHAR) 

NENDWHILE 

UIPRINT 

UFLAG=SUBSTRCCHAR, LOOKUP) 

UON FLAG GOTO 18,20,30,40,50,60,70 
Ue PRINT: FIRST#SECOND: \ GOTO: “4 


ev PRINT FIRST=SECOND \ GOTO: 1 
3@ PRINT FIRST*SECOND \ GOTO 1 
40 PRINT PIRST/SECOND \ GOTO 4 
58 PRINT FIRST*SECOND \ GOTO 1 
68 PRINT FIRST<SECOND \ GOTO 1 


78 PRINT FIRST>SECOND \ GOTO 1 

188 PRINT "Procedure Terminated Due to @ 
IHPUlss 4 

HEND 
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INPUT Get data from a device path 


Syntax: INPUT [#path,] [prompt,] variable [, variable...] 


Function: INPUT accepts input from the specified path. (The 
default is the keyboard.) When a procedure encounters 
INPUT, it displays a question mark and awaits data from the 
specified path. If you provide a string type prompt for INPUT, 
it displays the text of the prompt, rather than a question 
mark. 


INPUT stores the data it collects in the variable you specify. 
The type of the receiving variable must match the type of 
data received. 


Because INPUT sends data (the question mark prompt or the 
user-specified string prompt), it is really both an input and an 
output statement. This means that, if you use a path other 
than the standard input path, you should not use the 
UPDATE mode. If you do, the prompts produced by INPUT 
write to the file specified by the path number. 


If the data received does not match the type of data INPUT 
expects, it displays the message: 


**INPUT ERROR - RETYPE** 


followed by a new prompt. You must then enter the entire 
input line, of the correct type, to satisfy INPUT. For more 
information, see GET. 
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Parameters: 
path Either a variable containing the path number, 
_, or the absolute path number to the file or 
device from which you want to receive input. If 
you want to receive input from the keyboard, 
do not include a path number. 
prompt Text you type as a message to be displayed 
when BASICO9 executes an INPUT statement. 
variable The variable name in which you want to store 
the data received by INPUT. The type of vari- 
able must match the type of input. 
Examples: 


INPUT NUMBER,NAME$ ,LOCATION 
INPUT #PATHY Xs ¥,2 
INPUT “What is your selection: “;CHOICE 
c™ INPUT #HOST,"What’s your ID number? ",IDNUM 


Sample Program: 


This procedure calculates the day of the week for a specified 
date. It asks you for the date using the INPUT command. 


PROCEDURE weekday 

UDIM X,Y,D,M,CALC: INTEGER; DAY,MONTH:STRING([2]; 
YEAR: STRING[I 4]; WEEKDAY €7):STRING[Q] 

JDIM ANUM,BNUM,CNUM,DNUM,ENUM,FNUM,GNUM,HNUM, 
INUM: INTEGER 

PRINT USING "S88 ","Day of the Week Program "rar 
any year atier 1752" 


PRINT 

WPRINT “Enter day Ce.g.. 889% "s A: TNPUT DAY 

PRINT *- Enter month Ces,9g. 123 %. INPUT MONTH 

UPRINT = -Enter year Ceag. 198626 ": \ INPUT -YEAR 
o™ JY=VALCYEAR) \M=VALCMONTH) \D=VALCDAY) 


FOR x=1 TO 7 
JREAD WEEKDAYCX) 
UINEXT xX 
UANUM=INTC.6+1/M) 
JBNUM=Y-ANUM 
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UCNUM=M+12*ANUM 
UDNUM=BNUM/ 108 
DENUM=INTCDNUM/ 4) 
UFNUM=INTCDNUM) 
UGNUM=INTCS*BNUM/ 4) 
DHNUM=INTC13*CCNUM+19/5) 
UDINUM=HNUM+GNUM-FNUM+ENUM+D-1 
OINUM=INUM-7* INTCINUM/ 7) +1 


PRINT 
UPRINT “The day of the week on "5 M; "7"; D; 
7s Vs pe, os WEEKDAY CINUM2 


ODATA “Sunday™,™"Monday™, "Tuesday", “Wednesday”, 
“The sday' "Friday, “saturday” 
UEND 
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IN T Convert real number to whole number 


Syntax: INT(value) 


Function: Converts a real number to a whole number by trun- 
cating any fractional part of the real number. 
Parameters: 


value Any negative or positive real number. 


Examples: 
PRINT INTC77.89) 
PRINT INTCNUM) 
PRINT INTC-8.12) 


Sample Program: 


The RND function produces real numbers. This procedure uses 
INT to convert the real RND output to integer values. 


PROCEDURE integer 
UDIM T: INTEGER 
UFOR T=1 TO 1@ 
UR=RNDCS8@)-25 
UPRINT R,INTCR) 
EINEXT 7 

WEND 
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KILL Remove a procedure from memory 


Syntax: KILL procedure 


Function: Unlinks (removes) an external procedure from the 
BASICO9 procedure directory. If the procedure is not external, 
but resides in BASIC09’s workspace, KILL has no effect. 


Use KILL to remove auto-loaded (packed) procedures that are 
called by RUN or CHAIN. You can also use KILL with auto- 
loading procedures as a method to overlay programs within 
BASICO9. 


Warning: Be certain you do not KILL an active proce- 
dure. Also be certain that when you use RUN and KILL 
together, that both statements use the same string vari- 
able that contains the name of the procedure to RUN 


and KILL. 
Parameters: 
procedure The name of the external procedure you want 
to KILL. Procedure can either be a name or a 
variable containing the procedure name. 
Examples: 
PROCEDURENAME$ = "AVERAGE" 


RUN PROCEDURENAME $ 
KILL PROCEDURENAMES$ 


INPUT "Which test do you want to run? ",TESTS$ 
RUN TESTS$ 
Kit Pests 
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Sample Program: 


This procedure calls a procedure named Show to display ASCII 
values on the screen. When it no longer needs the Show proce- 
dure, it removes Show from memory using KILL. 


PROCEDURE produce 

LIDIM T, UsINTEGER 

CIDIM NUM,NUM1 ,NUM2, TABLE ,PROCNAME: STRING 
CIPROCNAME=SHOW 

LKITABLE="'123456789ABCDEF" 
LIFOR T=8 TO 15 

LIFOR U=1 TO 15 

LINUM1 =MID$CTABLE,T,1) 

LINUM2=MID$CTABLE,U,1) 

LINUM=NUM1+NUM2 (* parameter to pass to Show. 


LIRUN PROCNAMECNUM) 

LINEXT U 

LINEXT T 

UIKILL "PROCNAME' (*# remove Show from the workspace. 


UEND 


PROCEDURE SHOW 

LIPARAM NUM:STRING 
USHELL "DISPLAY "+NUM 
LEND 
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LAND Returns the logical AND of two numbers 


Syntax: LAND(num1,num2) 


Function: Performs the logical AND function on a byte- or 
integer-type value. The operation involves a bit-by-bit logical 


AND of the two numbers you specify. For instance, if you 
LAND 5 and 6, the logic is like this: 


Decimal 5 = Binary 0101 
Decimal 6 = Binary 0110 


0101 
AND 0110 


= 0100 = 4 Decimal 


Parameters: 
num! A byte- or integer-type number. 
num2 A byte- or integer-type number. 
Examples: 


PRINT LANDC11,12) 


PRINT LANDC $20 ,$FF) 


Sample Program: 


The following procedure asks eight questions and uses the eight 
bits of one byte (contained in the variable STORAGE) to indicate 
either a “yes” or “no” answer. If the answer is “yes,” it sets a 
corresponding bit to 1. If the answer is “no,” it sets a corre- 
sponding bit to 0, using LAND. This procedure operates in con- 
junction with the sample program for LXOR. 
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PROCEDURE questions 


LIFOR T 
LIREAD 


OGET # 
LIPRINT 
LIF AN 


LIELSE 


LENDIF 
LX=X+2 
LINEXT 


LIEND 

LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 
LIDATA 


ale 
QUESTION 


0, ANSWER 


SHER="y" 


r 


"Do you 
"Do you 
"Do you 
"Do you 
"Do you 
"Do you 
"Do you 
"Do you 


LIPRINT QUESTION; " (Y/N)? "; 


OR ANSWER="Y" THEN 


RUN summary (STORAGE) 


have more than 


use your 
use your 
use your 
use your 
use your 
Use your 


Color 
Color 
Color 
Color 
Color 
Color 


one Color Computer" 

for games" 

for word processing" 

for business applications" 


Computer 
Computer 
Computer 
Computer 
Computer 
Computer 


CIDIM QUESTION:STRING(G01; T: INTEGER; X,STORAGE:BYTE 
LIDIM ANSWER: STRING(1] 


LISTORAGE=LOR(STORAGE ,X) (* OR STORAGE if yes, 


LISTORAGE=LAND(STORAGE ,LNOT(X)) (# LAND STORAGE with NOT value if no. 


at home" 


at the office" 
more than two hours a day" 
share your Color Computer with others" 
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LE FT Returns characters from the left portion 
of a string 


Syntax: LEFT$(string,length) 


Function: Returns the specified number of characters from the 
specified string, beginning at the leftmost character. If length 
is the same as or greater than the number of characters in 
string, then LEFT$ returns all the characters in the string. 


Parameters: 
string A sequence of ASCII characters or a string 
variable name. 
length The number of characters you want to access. 
Examples: 


PRINT LEFTSC"HUTDOG™,32 


PRINT LEFT$CA$,6) 


Sample Program: 


The following procedure extracts the first name from a list of ten 
names with the LEFT$ function. 


PROCEDURE firstname 

DDIM NAMES:STRING; FIRSTNAME:STRING(1@] 
CPRINT "Here are the first names:" 

CIFOR T=1 TO 18 

LIREAD NAMES 

CPOINTER=SUBSTR(" ",NAMES) (* find space between first and last names. 
CIFIRSTNAME=LEFTS$CNAMES ,POINTER-1) (* extract first name. 
CIPRINT FIRSTNAME (* print first name. 

LINEXT T 

LIEND 

ODATA "Joe Blonski","Mike Marvel","Hal Skeemish","Fred Laungly" 


DIDATA "Jane Mistey", "Wendy Paston","Martha Upshong", "Jacqueline Rivers" 
CIDATA "Susy Reetmore", "Wilson Creding" 
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LEN Returns the length of a string 


Syntax: LEN(string) 


Function: Returns the number of characters in a string. 
Counts blanks or spaces as characters. 


Parameters: 
string A literal string or a variable containing string 
characters. 
Examples: 


PRINT LENC™ABCDEFGHIUJKLIN") 
PRINT LENCNAME$) 


NAME$ = "JOE" 
ADDRESS$ = "2244 LANCASTER" 
TOTALLEN = LENCNAME$)+LENCADDRESS$ ) 


Sample Program: 


The following procedure uses LEN to determine which name in a 
list is longest. 


PROCEDURE longname 

LIDIM NAMES ,LNAME:STRING; LONGEST,LENGTH: INTEGER 

LINAMES="" \LNAME="" \LENGTH=@ \LONGEST=0 

CIFOR T=1 TO 10 

LIREAD NAMES 

LILENGTH=LENCNAMES ) 

LIF LONGEST<LENGTH THEN 

ILONGEST=LENGTH 

CILNAME=NAMES 

LIENDIF 

LINEXT T 

LIPRINT "The longest name is "; LNAME; " with "; LONGEST; " characters." 
LIEND 

LIDATA "Joe Blonski","Mike Marvel","Hal Skeemish","Fred Laungly" | 
UIDATA "Jane Misty", "Wendy Paston", "Martha Upshong", "Jacqueline Rivers" 

VIDATA "Susy Reetmore", "Wilson Creding" 


IS LD SIE EES ELSE OY ET a I ET IT ES SEP I SE I I TS 
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LET Assigns a variable’s value 


Syntax: [LET] variable = expression 


Function: Assigns a value to a variable. BASICO9 does not 
require the LET statement to assign values but does accept it 
in order to be compatible with versions of BASIC that do 
require it. 


Parameters: 
variable The variable to which you want to assign a 
value. 
expression Either a numeric or string constant or a 
numeric or string expression. 
Notes: 


e The result of the LET expression must be of the same type 
as, or compatible with, the variable in which it is stored. 


e BASIC09’s assignment function accepts either = or := as 
assignment operators. The := form helps to distinguish 
assignment operations from comparisons (test for equality) 
and is compatible with Pascal programming. 


@ Use BASIC09’s assignment function to copy entire arrays or 
complex data structures to another array or complex data 
structure. The data structures do not need to be of the 
same type or shape, but the size of the destination struc- 
ture must be the same as or larger than the source struc- 
ture. This means the assignment function can perform 
unusual type conversions. For example, you can copy a 
string variable of 80 characters into a one-dimensional 
array of 80 bytes. 
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Examples: 
LET A = 5 
LET A := B 
ANSWER = A * B 
LET NAME$ := "JOE" 
NAME $ = FIRSTNAME$ + " " + LASTNAMES 


Sample Program: 


This procedure uses LET to assign a random value to the vari- 
able R. 


PROCEDURE getint 
UDIM T: INTEGER 
FOR T=1 TO 10 
ULET R=RNDC50)-25 
UPRINT R,INTCR) 
LINEXT T 

END 
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LNOT Performs a logical NOT on a number 


Syntax: LNOT(value) 


Function: Performs the logical NOT function on an integer or 
byte type number. The operation involves a bit-by-bit logical 
complement operation of the number you specify. For instance, 
if value is 188, the logic looks like this: 


188 Decimal = 10111100 Binary 


NOT 10111100 
= 01000011 


01000011 Binary = 67 Decimal 


LNOT changes each bit in a binary number to its complemen- 
tary binary value—all 1 values become 0 and all 0 values 
become 1. LNOT returns an integer result; it is not a Boolean 
operator. 


Parameters: 
value Any decimal or hexadecimal integer or byte 
number. Precede hexadecimal numbers with $. 
Examples: 


PRINT LNOTC88) 
A = LNOTCB) 


A = LNOTC$44) 


Sample Program: 


This procedure uses one byte (contained in the variable STOR- 
AGE) to indicate the results of eight questions. Each bit in the 
byte indicates a Yes or No answer (Yes=1 and No=0). The com- 
bination logic of LAND and LNOT masks the byte X so that it 
affects only the appropriate bit of STORAGE to set it to 0 if the 
answer is No. LOR sets the appropriate bit to 1 if the answer is 
Yes. The procedure operates in conjunction with the LXOR sam- 
ple program. 
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PROCEDURE questions 

LIDIM QUESTION:STRING(60)]; T: INTEGER: X,STORAGE:BYTE 
CIDIM ANSWER: STRING(1] 

LIX=1 

LIFOR T=1 10 8 

CIREAD QUESTION 

LIPRINT QUESTION; " (Y/N)? ": 

CIGET #0, ANSWER 

RINT 

LIF ANSWER="y" OR ANSWER="Y" THEN 
LISTORAGE=LOR(STORAGE,X) (* Answer is yes; Set bit to 1; 
LIELSE 

LISTORAGE=LAND(STORAGE ,LNOT(X)) (* Answer is no, set bit to @. 
LIENDIF 

LX=X#2 

LINEXT T 

LIPRINT STORAGE 

RUN summary(STORAGE) 

CIEND 

LIDATA "Do you have more than one Color Computer" 

LIDATA "Do you use your Color Computer for games" 

LIDATA "Do you use your Color Computer for word processing" 


LIDATA 
LIDATA 
UDATA 


LIDATA 


CIDATA "Do you 


"Do you 
"Do you 
"Do you 
"Do you 


use your Color Computer for business applications" 
use your Color Computer at home" 

use your Color Computer at the office" 

use your Color Computer more than two hours a day" 
share your Color Computer with others" 
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LOG Returns natural logarithm 


Syntax: LOG(number) 


Function: Computes the natural logarithm of a number that 
is greater than zero. BASICO9 returns the logarithm as a real 
type result. 


Parameters: 


number Any integer, byte, or real number. 


Examples: 
PRINT LOGC3.14159) 
LOGVALUE = LOGC88/P1) 


Sample Program: 


This procedure calculates the natural log and the log to base 10 
of the values 1-7. 


PROCEDURE logs 
DIM NUM,T: INTEGER 
LIFOR T=1 TO 7 
OPRINT "The LOG of "s T; " to the natural base = 
ec UGC TD 

DPRINT “The LOG of “ss Ts -*" to base 10 °=-"s 
LOG1@CT) 

LIPRINT 

UINEXT T 

LIEND 
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LOG10 Returns base 10 logarithm 


Syntax: LOG10(number) 


Function: Calculates the base 10 logarithm of a number. 
BASIC09 returns the logarithm as a real number. 


Parameters: 


number Any byte, integer, or real value. 


Examples: 
PRINT LOG10C€$45) 
PRINT LOG10CA) 
PRINT LOG10C€A/12) 


Sample Program: 


This procedure calculates the natural log and the log to base 10 
of the values 1-7. 


PROCEDURE logs 

UDIM NUM,T: INTEGER 

UFOR T=t TO 7 

UPRINT "The LOG of "; Ts; " to the natural base = 
me LUGE T 2 

UPRINT “The LOG of "s T: " to base 19 = a 
LOG1I@CT) 

UPRINT 

UNEXT T 

UEND 
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LOOP/ENDLOOP 


Establishes/Closes a loop 


Syntax: LOOP 
statement(s) 
ENDLOOP 


Function: Establishes a loop in which you can install EXITIF 
tests at any location. The LOOP and ENDLOOP statements 
define the body of the loop. EXITIF tests for a condition 
which, if TRUE, causes alternate actions, the transfer of pro- 
cedure execution to another routine, or both. 


If you do not include an EXITIF statement, the loop cannot 
terminate. 


Parameters: 
statement(s) One or more procedure lines to execute within 
the loop. 
Examples: 
LOOP 


COUNT = COUNT+1 

EXITIF COUNT 2 489° THEN 
DONE = TRUE 

ENDEXIT 

PRINT COUNT 

X=COUNT/2 

ENDLOOP 


INPUT Xa¥ 

LOOP 

PRINT 

EXITIF X<@ THEN 

PRINT "X became @ first" 
END 

ENDEXIT 

Kose 4 

EXITIF Y=@.- THEN 

PRINT "Y became @ first" 


a 
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END 
ENDEXIT 
¥uy=4 
ENDLOOP 


Sample Program: 


This procedure simulates a gambling machine that awards cash 
returns depending on a random selection of kinds of fruits. You 
begin with a stake of $25 and win or lose according to random 
selections of the procedure. 


The program uses LOOP/ENDLOOP to keep operating until you 
run out of cash. 


PROCEDURE bandit 

UDIM FRUIT1,FRUIT2,FRUIT3,STAKE: INTEGER; 
FRUITC18):STRING[6] 

USTAKE=25 

UIPRENT PRINT “You have $™* STAKEs ™ to play 
Wirth. 

FOR T=1 TO 1@ 

UREAD FRUITCT) 

UNEXT T 

LOOP 

UFRUIT1=RNDC9)+1 \FRUIT2=RNDC9)+1 \FRUIT3=RNDC9) +1 
UPRENT FRUITCRRUITIDs. 8 2 FRUITCERUIT2)3 * 
PRUITCFRUIT3) 

UIF FRUITCFRUIT1)=FRUITCFRUIT2) AND FRUITCFRUIT1)= 
FRUITCFRUIT3) THEN 

USTAKE=STAKE+12 

i ry = 

JIF FRUITCFRUIT1)=FRUITCFRUIT2) OR FRUITCFRUIT2)= 
FRUITCFRUIT3) THEN 

USTAKE=STAKE+2 

HELSE 

UIF FRUITCFRUIT1)=FRUITCFRUIT3) THEN 
USTAKE=STAKE +1 

ELSE STAKE=STAKE-1 

HENDIF 

LIENDIF 

HENDIF 

HEXITIF STAKE<1 THEN 

UPRINT 

PRINT "You’re Busted...Better go home." 
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PROCEDURE questions 

UDIM QUESTIONSSTRING(6@8)]= TI NTEGER: 
X,STORAGE* BYTE 

UDIM ANSWER: STRING[1] 

LIX = 1 

FOR T=T To 8 

UREAD QUESTION 

UPRINT QUESTION: * ©Y/NJ? 5 

GET #8,ANSWER 

LIPRINT 

ULF ANSWER ="*yv" OR ANSWER="Y¥" “THEN 
UISTORAGE=LORCSTORAGE, X) 

ELSE 

USTORAGE=LANDCSTORAGE ,LNOTCX)) 

VEND TF 

LIX=X*2 

LINEXT T 

LIPRINT STORAGE 

RUN summaryCSTORAGE) 

LIEND 

UDATA "Do you have more than one Color Computer" 
UDATA "Do you use your Color Computer for games" 
UDATA "Do you use your Color Computer for word 
processing” 

UDATA "Do you use your Color Computer for business 
applications” 

UDATA "Do you use your Color Computer at home" 
UDATA "Do you use your Color Computer at the 
office™ 

UDATA "Do you use your Color Computer more than 
two hours a day" 

UDATA "Do you share your Color Computer with 
others" 
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LXOR Returns logical XOR of two numbers 


Syntax: LXOR(valuel,value2) 


Function: Performs the logical XOR function on two-byte, or 
integer-type, values. For instance, if you LXOR the numbers 5 
and 6 the logic is like this: 


Decimal 5 = Binary 0101 


Decimal 6 = Binary 0110 
0101 

LXOR 0110 

= 0011 = 3 Decimal 


If one bit or the other bit in the evaluation is 1, but not both, 
LXOR returns a result of 1. Otherwise, LXOR returns a 
result of 0. 


Parameters: 
valuel A byte or integer number. 
value2 A byte or integer number. 
Examples: 


PRINT LXORC11,12) 


PRINT LXORC$2@,$FF) 


Sample Program: 


The following program summarizes the results of the sample 
program for LOR. The LOR program stored the answers to eight 
questions in a single byte. This procedure reads the byte and 
displays appropriate comments. LXOR checks to see if two of the 
answers are “yes” or “no.” 
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ENDEX ALT 

PRINT "Your stake is now $"3; STAKE; "." 

OPRINT 

PRINT 

OINPUT “Press ENTER to pull again...",2Z$ 
OENDLOOP 

HEND 

ODATA “ORANGE","APPLE","CHERRY","LEMON", "BANANA" 
ODATA “PEAR"™,"PLUM", “PEACH, "GRAPE","APRICOT™ 


ne ee 
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LOR Returns logical OR of two numbers 


Syntax: LOR(valuel,value2) 


Function: Performs the logical OR function on a byte- or 
integer-type value. The operation involves a bit-by-bit logical 
OR operation on two values. For instance, if you LOR the 
numbers 5 and 6, the logic is like this: 


Decimal 5 = Binary 0101 
Decimal 6 = Binary 0110 


0101 
OR 0110 


= 0111 = 7 Decimal 


If one bit or the other bit is 1, LOR returns a result of 1. 
Otherwise, LOR returns a result of 0. 


Parameters: 
valuel A byte or integer number. 
value2 A byte or integer number. 
Examples: 


PRINT LORETT. Te) 


PRINT LORC$20,$FF) 


Sample Program: 


This procedure stores the answers to eight “yes” or “no” ques- 
tions in one byte, named STORAGE. If you answer “yes” to a 
prompt, the procedure sets a corresponding bit to 1. If you 
answer “no” to a prompt, the procedure sets a corresponding bit 
to 0. The procedure uses LOR to set bits to 1 by masking all bits 
except the one it needs to set. The procedure operates in con- 
junction with the LXOR sample program. 
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PROCEDURE summary 

DIM TeINTEGER: A,B X. TEST, TESTS: BYTE? SUMMARY: 
STRING(S@ 3 

OPARAM STORAGE: BYTE 

LA=0 \B=@ 

PRINT \ PRINT 

OPRINT “The following iS a summary of the 
questionnaire answers:" 

UPRINT 

DPRINT “The surveyee: * 

LIX = 1 

OFOR T=1 TO 8 
OTEST=LANDCSTORAGE , X) 
DREAD SUMMARY 

OIF TEST>@ THEN 

OPRINT TABC19); SUMMARY 
ENDIF 

UX=X*2 

UNEXT T 

OIF LANDCSTORAGE ,128)>@ THEN 
LIA=1 

LIENDIF 

OIF LANDCSTORAGE ,64)>8 THEN 
LIB=1 

DIENDIF 
OTEST2=LXORCA,B) 


OIF TEST2@=1 THEN 
EPRINT “This: computer owner either uses the 
computer? 

OPRINT “more than two hours a day or shares it 
with others." 

OPRINT "This is a heavy use situation.” 

DENDIF 

OTEST2=LANDCA,B) 

[LE TEST2=1 THEN 

OPRINT “This computer user uses the computer more 
than two" 

OPRINT “hours per day and shares it with others. 
This is a" 

OPRINT “super heavy use situation.” 

HENDIF 

WIEND 

ODATA "Uses more than one computer" 

ODATA “Plays games" 


ee mene namrnrierneeneemmmesmmereeeemerneene meee memes asaaaaaaacaaaaamaaaaaaaaaaamaamaaamammaaamaaam 
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UDATA 
UDATA 
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“Uses the computer for word processing™ 
“Uses the computer for business" 

“Keeps a Color Computer at home" 

"Keeps a Color Computer at the office" 
“Uses the computer more than two hours a 


“Shares the computer with others" 
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MID$ Returns characters from within a string 


Syntax: MID§(string,begin,length) 


Function: Returns a substring length characters long, begin- 
ning at begin. Use MID$ to “take apart” a string consisting 
of a number of elements. 


Parameters: 
string A sequence of string type characters or a 
string type variable. 
begin The position (an integer value) in string of the 
first character to retrieve. 
length The number of characters you want to retrieve. 
Examples: 
NAMES = “JONES, JOHN M.™ 


LASTNAME$S = MIDSCNAMES ,8,6) 
FIRSTNAME$ = MID$CNAMES,1,5) 
INITIAL$ = MID$CNAMES$ ,15,2) 


Sample Program: 


This procedure reverses a word or phrase you type. MID$ reads 
each character in your phrase from the end to the beginning. 


PROCEDURE reverse 

ODIM PHRASE:STRING; T,BEGIN: INTEGER 
PRINT “Type a word or phrase you want (ee. 
reverse:"'; 

WJPRINT 

OINPUT PHRASE 


UBEGIN=LENCPHRASE ) 
OPRINT “This is how your phrase looks backwards:" 
(FOR T=BEGIN TU 1 STEP =1 

DOPRINT MID$CPHRASE,T,1); 

UNEXT T 

PRINT 

HIEND 


—— aaa 
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MOD Returns modulus of a division 


Syntax: MOD(number1,number?2) 


Function: Returns the modulus (remainder) of a division. 
MOD divides numberl by number? and calculates the remain- 
der. You can use MOD to put a limit on a numeric variable. 
For instance, regardless of the value of X, MOD(X,3) produces 
numbers only in the range 0 through 2. MOD(X,5) produces 
numbers only in the range of 0 through 4. 


You can use MOD to cause repeating sequences. For instance, 
in a loop, MOD(X,3) produces a repeating sequence of 0, 1, 2, 
where X increases by 1 in each step of the loop. 


Parameters: 
number! A byte, integer or real number dividend. 
number2 A byte, integer or real number divisor. 
Examples: 


PRINT MODC99,5) 
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Sample Program: 


This procedure uses MOD to execute repeatedly routines that 
display asterisks on the screen. There are eight subroutines that 
the MOD function selects over and over through 100 passes. 


PROCEDURE stardown 

UDIM TeINTEGER 

OSHELL “TMODE -PAUSE™ 

OFOR T=1 TO 1900 

OON MODCT,8)+1 GOSUB 10,20,30,48,50,60,70,80 
UNEXT T 

OSHELL “"TMODE PAUSE" 

OEND 

1@0OPRINT USING "S16*","*#" \ RETURN 
2G0PRINT USING "S190°","#*" \ RETURN 
3O0PRINT USING "S10%","#*##" \ RETURN 
4@0PRINT USING "S10", "##*#"™" \ RETURN 
SOOPRINT USING "S1Q%", eeeee" \ RETURN 
GO@OPRINT USING "S19", eee" \ RETURN 
7O@OPRINT USING "S1@%","#**" \ RETURN 
S8@OPRINT USING "S10*","*#" \ RETURN 
HEND 
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N E XT Causes repetition in a FOR loop 


Syntax: FOR variable = init val TO end val [STEP 
value] 
[procedure statements] 
NEXT variable 


Function: NEXT forms the bottom end of a FOR/NEXT loop. 
Any program statements between FOR and NEXT are exe- 
cuted once for each repetition of the loop, from the initial 
value to end value. 


Parameters: 
variable Any legal numeric variable name. 
init val Any numeric constant or variable. 
end val Any numeric constant or variable. 
value Any numeric constant or variable. 
procedure Procedure lines you want to execute within 
statements the loop. 


For more information, see FOR/NEXT/STEP. 
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NOT Returns the complement of a value 


Syntax: NOT(value) 


Function: Returns the logical complement of a Boolean value 
or expression. 


Parameters: 
value A Boolean value (True or False), or an expres- 
sion resulting in a Boolean value. 
Examples: 


DIM TEST:BOOLEAN 
WHILE NUPCTESTS: De 
A=A+1 

TEST #A=B 

ENDWHILE 


Sample Program: 


This procedure redirects the current directory listing to a file 
named Dirfile. It then opens Dirfile and reads the contents, dis- 
playing each line on the screen. It uses NOT in a WHILE/END- 
WHILE loop to make sure that the end of the file has not been 
reached before trying to read another entry. 


PROCEDURE readfile 

UDIM A:STRING([88@] 

JDIM PATHS BY Fe 

MSHELL “DIR > dirfile” 
OPEN #PATH,"dirfile":READ 
OWHILE NOT EOQFC#PATH) DO 
UREAD #PATH,A 

UP-RINT A 

NENDWHILE 

DCLOSE #PATH 

HEND 
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ON ERROR/GOTO 


Establishes an error trap 


Syntax: ON ERROR [GOTO linenum] 


Function: Sets an error trap that transfers control to the spec- 
ified line number in a procedure. This lets your program 
recover from an error and continue execution. To use these 
commands, your program must have at least one numbered 
line—the line to branch to in the event of an error. 


Parameters: 
linenum The line to which you want BASICO9 to 
branch should an error occur. 
Notes: 


e ON ERROR GOTO is effective only with non-fatal, run- 
time errors. If such an error occurs without a preceding ON 
ERROR GOTO statement, BASICO9 enters the DEBUG 
mode. You must specify ON ERROR GOTO before an error 
occurs. 


e You turn on error trapping by specifying ON ERROR 
GOTO linenum. You turn off error trapping by specifying 
ON ERROR without a line number. 


@ Use ON ERROR GOTO with the ERR function (that 
returns the code of the last error) to specify a particular 
action for a particular error. You can also use ERROR to 
simulate an error to test error trapping. For more informa- 
tion on this, see ERROR. 
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Examples: 


ODIM FILENAME:STRING 

ODIM PATH: INTEGER 

1Q0INPUT "Name of file to create? ",FILENAME 
HOON ERROR GOTO 180 

OCREATE #PATH,FILENAME: UPDATE 

WEND 

1@@0PRINT "That file already exists...please 
choose another name..." 

GOTO 19 

LIEND 


Sample Program: 


If you created a directory file with the GET sample program, 
you can use this procedure to delete files from the original direc- 
tory using key characters. For instance, you might type XX as 
key characters. This means that any filename containing the 
character group XX is deleted. You can select any key characters 
you wish, but be sure they apply only to files you want to 
delete. 


If you want to delete all the files in the directory, type an aster- 
isk (*) when asked for key characters. 


This procedure uses ON ERROR to let the procedure continue, 
even if a directory entry cannot be deleted—if an entry is a sub- 
directory. Without the ON ERROR function, the procedure 
would produce an error and cease execution when it tried to 
delete a subdirectory. 


PROCEDURE purge 

OREM Use caution with this procedure 
OREM Be sure to specify key characters 
OREM that exist only in the files you 


OREM want to delete! 


ODIM PATH: INTEGER 

UDIM NAMEC188)9:STRING 

ODIM WILDCARD: STRING 

UX=@ 

DOPEN #PATH,“dirfile™:READ 
OWHILE NOTCEOFC#PATH)) DO 
UX=X+1 

UREAD #PATH,NAMECX) 


eee eee reer === 


11-98 


BASICO9 Command Reference / 11 


UENDWHILE 

UFOR T=1 TO X 
UPRINT NAMECT), 
LINES 7 


UFOR T=1 TO X 
UON ERROR GOTO 168 


THEN 


UDELETE NAMECT) 
UENDIF 

1OUNEXT T 

LEND 


1OOUPRINT "*O*Q*QERROR,O"; NAMECT); 


deleted...continuing."™ 
GOTO 18 
UEND 


BPRINT “DELETING *s- NAMECTI« © 2 


UINPUT “Wildcard Characters...",WILDCARD 


UIF SUBSTRCWILDCARD,NAMECT))>@ OR WILDCARD="«" 


"cannot be 
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ON/ GOSUB Jumps to subroutine on a 


specified condition 


Syntax: ON pos GOSUB linenum [,linenum,...] 


Function: Transfers procedure control to the line number 
located at position pos in the list of line numbers immediately 
following the GOSUB command. For example, if pos equals 1, 
BASICO9 branches to the first line number it encounters in 
the list. If pos equals 2, BASICO9 branches to the second line 
number it encounters in the list. If pos is greater than the 
number of items in the list, execution continues with the next 
command line. To use ON/GOSUB you must have numbered 
lines to match the line numbers in your list. End the routines 
accessed by ON/GOSUB with a RETURN statement. 


Parameters: 
pos An integer value pointing to a line number in 
a list of line numbers. 
linenum Any numbered line in the procedure. 
Examples: 


PRINT "You can now: (1) End the program C2) Print 
the results" 


PRINT ™ C3) Try again C4) Start 
a new program" . 
INPUT “Type The Jerter of your choice: * CHOICE 


ON CHOICE GOSUB 108, 200, 300, 408 
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Sample Program: 


This procedure uses MOD to execute repeatedly a sequence of 
( \ GOSUB commands. A loop of index of 80 causes execution to 
jump to each line number in the list 10 times. 


PROCEDURE repeat 

USHELL “TMODE -PAUSE" 

DIM TtINTEGER 

(FOR T=1 TO 8@ 

JON MODCT,8)+1 GOSUB 18,20,308,408,50,60,70,820 

UINEXT T 

USHELL “TMODE PAUSE™ 

UEND 
1BCIPRINT USING “Si07".4e™ \ RETURN 
2SLiPRiINT USING “S19*™, "sea" \ RETURN 
SUUPRINT USING "S1G*", "see \ RETURN 
4QUPRINT USING "S19", "Sexee" \ RETURN 
SOUPRINT USING "S1Q4", "xxxee" \ RETURN 
SQUPRINT USING: "STO." eeee" \ RETURN 
7OLUPRINT USING “S18°" “see™ \ RETURN 

om SOUPRINT USING. S71 G4"  “ee™ \ RETURN 
DEND 
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ON/ GOTO Jump to line number on a 


specified condition 


Syntax: ON pos GOTO linenum [,linenum,...| 


Function: Transfers procedure control to the line number 
located at position pos in the list of line numbers immediately 
following the GOTO command. For example, if pos equals 1, 
BASICO9 branches to the first line number it encounters in 
the list. If pos equals 2, BASICO9 branches to the second line 
number it encounters in the list. If pos is greater than the 
number of items in the list, execution continues with the next 
command line. To use ON/GOTO you must have numbered 
lines to match the line numbers in the list. 


Parameters: 
pos An integer value in a range from 1 to the 
number of items in the list following GOTO. 
linenum Any numbered line in the procedure. 
Examples: 


PRINT "You can now: (1) End the program (2) Print 
the results" 


PRINT " €3) Try again €4) Start 
a new program" 
ENPUL *lype The letter of your choice: " choice 


ON CHOICE GOTO 108, 200, 300, 408 


Sample Program: 


This procedure converts decimal numbers to binary. It uses ON 
GOTO to execute the operation you select from a menu: Convert 
a number, display the result of all conversions, or end the 
program. 


PROCEDURE bicalc 
ODIMONUMBER,NUM,X,STORAGE: INTEGER;UBI : STRING; 
DARRAYCS8@ ,2)9:STRING 

UCOUNT=9 
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1@UBI=""" \NUMBER=@8 \NUM=@ \X=@8 \STORAGE=@ 
UINPUT "Number to convert to binary '',NUMBER 
HIF NUMBER=@ THEN END 

DENDIF 

UNUM=LOG18CNUMBER)/.3 

UNUM=2*NUM \STORAGE=NUMBER 

DREPEAT 

UX=NUMBER/NUM 

UIF X>@ THEN BI=BI+'1" 
UNUMBER=MODCNUMBER ,NUM) 

ELSE BI=BI+'"g" 

DENDIF 

UNUM=NUM/2 

NUNTIL NUM<=1 

HIF NUMBER>@ THEN 

Upl=Ble"y" 

DELSE*BI=BI+"g" 

DENDIF 

UPRINT STORAGE: “" = “+ Bls ™ in binary." 
UPRINT 

NCOUNT=COUNT +1 

UARRAYCCOUNT ,1)=STR$CSTORAGE) 
UARRAYCCOUNT ,2)=BI 

T2ZUPRINT “Do you want to: €1) Convert another 
number." 

UPRINT “QOOOOOOOOUOOOO00¢ 2) Display all calculations 
thas far.” 

UPRINT “QOODODOOUOOOOOOOC3) End the program." 
DISPUT “Enter: 1. 2. of Sy. 0" schoice 

UON choice GOTO 10,280,380 

DEND 

COLUFOR T=1 TO COUNT 

UPRINT ARRAYCT,1)93; "™ = "s ARRAYCT,2) 
UNEXT T 

UGOTO 12 

SOUPRINT \ PRINT " Program Terminated" 
DEND 
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OPEN Opens a path to a device 


Syntax: OPEN #path,“pathlist” [access mode]|{ + access 
mode|[ +...] 


Function: Opens an input/output path to a disk file or to a 
device. When you open a file, you can select one or more of the 
following access modes: 


Mode 
READ 
WRITE 
UPDATE 
EXEC 


DIR 


Parameters: 


path 
pathlist 


access mode 
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Function 


Lets you read (receive) data from a file or 
device but does not allow you to write (send) 
data. 


Lets you write data to a file or device but does 
not allow you to read data. 


Lets you both read from and write to a file or 
device. 


Specifies that the file you want to access is in 
the current execution directory. 


Specifies that the file you want to access is a 
directory-type file. 


The variable in which BASICO9 stores the 
number of the newly opened path. 


The route to the file or device to be opened, 
including the filename if appropriate. 


The type of access the system is to allow for 
the file or device. Use a plus symbol to specify 
more than one type of access. 
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Notes: 


@ The access mode defines the direction of I/O transfers. 


‘aa 


@ Because OS-9 files are byte-addressed and are unformat- 
ted, you can set up the filing system you want for a partic- 
ular application. Your system can read the data contained 
in a file as single bytes or in groups of any size you want. 


@ You can expand a file using PRINT, WRITE, or PUT state- 
ments to write beyond the current end-of-file. | 
Examples: 
UPEN #1 RANS, “transportation sUPDATE 
OPER #SPuck ."7uger4/ report WRITE 


OPEN #OUTPATH,name$:UPDATE+EXEC 


Sample Program: 


cy This procedure opens a path to both the SYS directory on Drive 
/DO and the error message file. 


PROCEDURE readerr 

UDIM A:STRING[8@] 

UDIM PATH: BYTE 

OPEN #PATH,"/D9/SYS/ERRMSG": READ 
TIWHILE EOF C#PATHI<> TRUE DO 

UREAD #PATH,A 

LIPRINT A 

HENDWHILE 

OCLOSE #PATH 

WEND 
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OR Performs a Boolean OR operation 


Syntax: operand! OR operand2 


Function: Performs an OR operation on two or more values, 
returning a Boolean value of either TRUE or FALSE. 


Parameters: 


operand] Either numeric or string values. 
operand2 


Examples: 
PRINT A>3 OR B>3 


PRINT AS#™"YES™ or BSa"YES" 
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Sample Program: 


This procedure asks you to type a word or phrase, then converts 

ef all lowercase characters to uppercase. It uses OR to test for a 
character in your word or phrase that is outside of the ASCII 
values for lowercase letters. If it is, the character does not need 
converting. 


PROCEDURE uppercase 
UDIM PHRASE ,NEWSTRING:STRING[I8@1]; CHARACTER: 
SUTRINGE1 Is TyX2 INTEGER 
UNEWSTRING=""' \PHRASE="" 
PRINT "Type a phrase in lowercase and I will make 
it. uppercase.” 
LINPUT PHRASE 
FOR T=1 TO LENCPHRASE) 
LUICHARACTER=MID$CPHRASE,T,1) 
UX=ASCCCHARACTER) 
OIF X<97 OR X9122 THEN 
UNEWSTRING=NEWSTRING+CHARACTER 
LELSE 

LX=X-32 
, UNEWSTRING=NEWSTRING+CHR$CX) 
LIENDIF 
NEXT T 
UIPHRASE=NEWSTRING 
UNEWSTRING=""! 
UPRINT PHRASE 
HEND 
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PARAM Establishes variables to receive from 
another procedure 


Syntax: PARAM variablel,...][:typell;variablelf,...][:typel 
Evil 


Function: Defines the parameters that a called procedure 
expects to receive from the procedure that calls it. When 
using PARAM, be sure that the total size of each parameter 
in the calling procedure’s RUN statement is the same as the 
defined size in the called procedure’s PARAM statement. 


Parameters: 
variable A simple variable, an array structure, or a 
complex data structure. 
type Byte, Integer, Real, Boolean, String, or user 
defined. 
Notes: 


e BASICO9 checks the size of each parameter to prevent acci- 
dental access to storage other than that assigned to the 
parameter. However, BASICO9 does not check that parame- 
ters are of the proper type. In most cases you must be sure 
that types evaluated in RUN statements match the types 
defined in the PARAM statements. 


However, because BASICO9 does not perform type checking, 
it is possible to perform useful but normally illegal type 
conversions of identically-sized data structures. For example, 
you could pass a string of 80 characters to a procedure 
expecting a byte array of 80 elements. Each character in 
the string is assigned a corresponding position in the 
array. 


@ You declare simple arrays by using the variable name, 
without a subscript, in a PARAM statement. 
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@ You can declare several variables of the same type by sepa- 
rating them with commas. To separate variables of differ- 
ent types, follow each type group with a colon, the type 
name, and then a semicolon. 


e If you do not include a maximum length for a string vari- 
able enclosed in brackets following the type, like this: 


DLE Tames Ss tri ngtes) 


BASICO9 uses a default length of 32 characters for strings. 
You can declare shorter or longer lengths, to the capacity of 
BASICO09’s memory. 


@ Arrays can have one, two, or three dimensions. The 
PARAM format for dimensioned arrays is the same as for 
simple variables except you must follow each array name 
with a subscript, enclosed in parentheses, to indicate its 
size. The maximum array size is 32767. 


Arrays can be either of the standard BASICO9 type, or of a 
user-defined type. To create your own data types for simple 
variables, arrays, and complex data structures, see TYPE. 


Examples: 


PARAM NUMBER: INTEGER 


PARAM NAMESSTRING(I CS] ;ADDRESS# STRING LSE Is 21P x 
INTEGER 


PARAM NOT Ne, NOS? REAL s NO4 NOS. NOG: INTEGER: NO7: 
BY VE 


Sample Program: 


The first procedure asks you to enter a decimal number. Then, it 
asks you to choose whether you want to convert the number to 
binary or hexadecimal. Depending on your choice, the procedure 
calls (using RUN) either a procedure named Binary or a proce- 
dure named Hex. It passes the number you typed to the appro- 
priate procedure for conversion. 
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PROCEDURE convert 

UDIM NUMBER,CHOICE: INTEGER 

PRINT USING “SO8*"; “Hexadecimal - Binary 
Conversion Program" 

LIPRINT 

19@0JINPUT “Number to convert...'',NUMBER 

OIF NUMBER=98 THEN 

WIEND 

ENDIF 

UINPUT “Choose: (1) Binary or €2) Hex...";CHOICE 
HON CHOICE GOTO 286,38 

2B@URUN BINARY CNUMBER) 

GOTO 18 

3@URUN HEXCNUMBER) 

UGOTO 18 

WEND 


PROCEDURE binary 

UDIM NUM,X,STORAGE: INTEGER; BI:STRING; 
ARRAYCS@,2):STRING 

LIPARAM NUMBER: INTEGER 
UCOUNT=2 

UBI="" \NUM=@ \X=8 \STORAGE=9 
UNUM=LO0G18CNUMBER)/.3 
UNUM=2*NUM \STORAGE=NUMBER 
UREPEAT 

UX=NUMBER/NUM 

OIF X>@ THEN 

DptaBs ia" 
ONUMBER=MODCNUMBER , NUM) 

ELSE 

UBI=BI+"g" 

HENDIF 

LINUM=NUM/e2 

UUNTIL NUM<=1 

OIF NUMBER>@ THEN 

WBI=B ie." 

VEGSE 

UBI=BI+"g" 

LIENDIF 

UPRENT STORAGE: -** «°° By" in binary.” 
UPRINT 

LIEND 
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PROCEDURE hex 

UDIM NUM,X,STORAGE: INTEGER; TABLE,HX:STRING; 
ARRAYCS@,2):STRING 

LIPARAM NUMBER: INTEGER 
UTABLE="123456789ABCDEF" 
UHX=""*"¥ \NUM=@8 \X=8@ \STORAGE=28 
UINUM=LOG18CNUMBER)/1.2 
UNUM=16*NUM \STORAGE=NUMBER 
UREPEAT 

UX=NUMBER/NUM 

OIF X>@ THEN 
HIHX=HX+MID$CTABLE,X,1) 
UINUMBER=MODCNUMBER ,NUM) 

HELSE HX=HX+"g" 

ENDIF 

LINUM=NUM/16 

UUNTIL NUM<=1 

IF NUMBER>@ THEN 
UHX=HX+MID$CTABLE ,NUMBER,1) 
ELSE 

LIHX=HX+""g" 

LIENDIF 

OPRINT STORAGE; “" = ": HX: " in hexadecimal." 
LIPRINT 

WIEND 


11-111 


BASICO9 Reference 


PAUSE Suspends execution and enters Debug 


Syntax: PAUSE text 


Function: Suspends the execution of a procedure and causes 
BASICO09 to enter the DEBUG mode. If you include text with 
the PAUSE command, it is displayed on the screen. 


Place PAUSE statements in a program temporarily to observe 
the way in which the procedure operates and to track down 
programming errors. When the procedure is operating cor- 
rectly, remove the PAUSE statement. 


After using DEBUG, you can continue execution of the paused 
procedure with the CONT command. 


Parameters: 
text A message you want PAUSE to display on the 
screen when BASICO9 executes the statement. 
Examples: 
PAUSE 


PAUSE The array is now full. 
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P EEK Returns the value in a memory location 


co” 

Syntax: PEEK(mem) 

Function: Returns the value of a memory byte as a decimal 
integer. The value returned is in the range 0 to 255. PEEK is 
the complement of the POKE statement. 

See also ADDR. 

Parameters: 

mem An integer value representing the location of 
the memory byte you want to examine. The 
memory byte is relative to the current pro- 
cess’s address space. 

Examples: 

‘= PRINT PEEKC15250@) 
MEMVAL = PEEKC4450@) 
- 
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Sample Program: 


This procedure asks you to type a phrase in uppercase charac- 
ters. It then uses ADDR to locate the area in memory where 
BASICO9 stores the phrase. Next, it reads each character from 
memory with PEEK, converts it to lowercase if necessary, and 
pokes the new value back into the same location. When the pro- 
cedure displays the contents of the phrase, it is all lowercase. 


PROCEDURE lowercase 

DIM LOC, TeINTEGER: PHRASE:STRINGLSO) 

OPRINT “Type a phrase in UPPERCASE and I[’11 make 
it lowercase." 

HINPUT PHRASE 

ULOC=ADDRCPHRASE ) 

OFOR T=LOC TO LOC+LENCPHRASE ) 
LX=PEEKCT) 

HIF X32 AND X<9O1 THEN 
UX=X+32 

UPGKE T,X 

LIENDIF 

UNEXT T 

PRINT PHRASE 


— 


LEND 
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P I Returns the value of pi 


Syntax: PI 


Function: Returns the constant value 3.14159265. 
Parameters: None 


Examples: 


PRINT "The area of a circle with a radius of 6 
inches is ™:PI#*#6*2 


Sample Program: 


This procedure uses the formula (PI+2)/15 as a basis for calcu- 
lating a screen position. Taking the sine of the formula, it prints 
a sine wave of asterisks down the screen. 


PROCEDURE picalc 

DIM FORMULA,CALCULATE,POSITION:REAL 
USHELE “DISPLAY gC" 
UFORMULA=CPI+2)/15 
UCALCULATE=FOQRMULA 

USHELL “TMODE -PAUSE™ 

UFOR T=8 TO 1820 
LIICALCULATE=CALCULATE+FORMULA 
UPOSITION=INTCSINCCALCULATE)*10+16) 
UPRINT TABCPOSITION); ‘#* 

INERT 7 

SHELL. “TMODE PAUSE” 

LEND 


I AE SST A BIE ERIE TEE TE PE SE SOE DE TE SEI LOE HPS BI AE IRAE LE I PI OE A CERI EAE EEE 
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POKE Stores a value in a memory location 


Syntax: POKE mem,value 


Function: Stores a value at the specified memory address, rel- 
ative to the current process’s address space. Mem is an abso- 
lute address at which BASICO9 stores a byte type value. 
POKE is the complement of the PEEK statement. 


You should use care when using POKE. Because it changes 
the value in memory, a POKE to the wrong portion of memory 
could cause OS-9, BASICO9, or your procedures to malfunction 
until you reboot the system. 


See also ADDR. 


Parameters: 
mem An integer value representing the location of 
the memory byte you want to change. 
value The value to store in the specified memory 
location. 
Examples: 


PORE- Loeoe gil 
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Sample Program: 


This procedure asks you to type a phrase in uppercase charac- 
ters. It then uses ADDR to locate the area in memory where 
BASICO9 stores the phrase. Next, it reads each character from 
memory, converts it to lowercase if necessary, and uses POKE to 
store the new value back in the same location. When the proce- 
dure next displays the contents of the phrase, it is all lowercase. 


PROCEDURE lowercase 

UDIM LOC,T: INTEGER; PHRASE:STRING[8@] 

UPRINT “Type a phrase in UPPERCASE and I’1l make 
it lowercase." 

HINPUT PHRASE 

PILOC=ADDRCPHRASE ) 

FOR T=LOC TO LOC+LENCPHRASE) 
UIX=PEEKCT) 

HIF X>32 AND X<91 THEN 
UX=X+32 

OPOKE Tax 

WENDIF 

UNEXT T 

LIPRINT PHRASE 

WEND 


SS ESS RP TSS SE (I TS ERI SP I SF I ES ES RT EE EO REET 


11-117 


BASICO9 Reference 


POS Returns cursor’s column position 


Syntax: POS 


Function: Returns the current column position of the cursor. 
Parameters: None 


Examples: 
PRINT POS 


Sample Program: 


This procedure is a simple typing program that uses POS to 
make sure that words are not split when you type to the end of 
the screen. After you type 25 characters on a line, the procedure 
breaks the line at the next space character. 


PROCEDURE wordwrap 
DIM CHARACTER: STRING[1] 


JIPRINT USONG “Ss2°"s "Word Wrap Program” 
PRINT USING “S32""s “Press [CTRLILC] to Exit” 
UPRINT 

TISHELL. *TMODE -ECHO™ 

OWHILE CHARACTER<>" " DO 

GET #1,CHARACTER 

UPRINT CHARACTER; 

OIF POS>25 AND CHARACTER="" " THEN 
LIPRINT CHR$C13) 

VEN ELF 
DENDWHILE 


SHELL. “TMODE. ECHO” 
LEND 
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PRIN T Displays text 


Syntax: PRINT [#path] [TAB(pos);] datal;data...] 


Function: Prints numeric or string data on the video display 
unless another path is specified. 


Parameters: 


path 


pos 


data 


Notes: 


The number corresponding to an opened device 
or file. If you do not specify path, the default 
is #1, the video screen (standard output 
device). To print to another device or file, first 
OPEN a path to that file or device (see 
OPEN). 


A column number that tells TAB where to 
begin printing. Specify any number from 0 to 
the width of your video display. 


Any numeric or string constant or variable. 
Enclose string constants within quotation 
marks. All data items must be separated by a 
semicolon or comma. 


@ If you specify more than one data item in the statement, 
separate them with commas or semicolons. 


e If you use commas, PRINT automatically advances to the 
next tab zone before printing the next item. In BASICO9, 
tab zones are 16 characters apart. 


e If you use semicolons or spaces to separate data items, 
BASICO9 prints the items without any spaces between 
them. BASICO9 begins the next print item immediately fol- 
lowing the end of the last print item. 


e If you end a print item without any trailing punctuation, 
PRINT begins printing at the beginning of the next line. 
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If the data being printed is longer than the display screen 
width, PRINT moves to the next line and continues print- 
ing the data. 


TAB causes BASICO9 to begin displaying the specified data 
at the column position specified by TAB. If the output line 


is already past the specified TAB position, PRINT ignores 
TAB. 


You can concatenate items for printing using the plus (+) 
symbol, for example: print “hello "+name$+" " 
+lastname$. 


PRINT displays REAL numbers with nine or fewer digits 
in regular format. It displays REAL numbers with more 
than nine digits in exponential format. For example, 
1073741824 is displayed as 1.07374182E+99. 


You must enclose string constants within quotation marks. 


Examples: 


PRINT A$ 


PRINT "Menu Items" 


PRINT COUNT 


PRINT VALUE,TEMP+(€n/2.5),LOCATIOQONS 


PRINT #PRINTER_PATH,"The result is ";NUMBER 


PRINT #OUTPATH FMT$,COUNT,VALUE 


PRINT “what iS” *NAaMese'’s eager “> 


PRINT “INDEX+ “st sTABCeS)<"VALUE® “eVOLUE 
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Sample Program: 


This procedure asks you to type a word or phrase, then displays 
it backwards by reading each character from end to beginning 
and using PRINT to display it on the screen. 


PROCEDURE reverse 

UDIM PHRASE,TITLE:STRING; T,BEGIN: INTEGER 

UDIM INSTRUCTIONS: STRING[43] 

UTITLE="Word Reversing Pregram™ 
HINSTRUCTIONS="Type a word or phrase you want to 
reverse: " 

UPRINT TLE 

De Ds ec eee 

UWHILE PHRASE<>"" DO 

LIPRINT 

UPRINT INSTRUCTIONS 

UWINPUT PHRASE 

(IBEGIN=LENCPHRASE ) 

UPRINT “This is how your phrase looks backwards:"™ 
FOR T=BEGIN TO 1 STEP -1 

PRINT MID$CPHRASE,T,1); 

UNEXT T 

PRINT 

HENDWHILE 

LIEND 
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PRINT USING Displays formatted text 


Syntax: PRINT [#path] USING [format,] data|;data...] 


Function: Prints data using a format you specify. This state- 
ment is especially useful for printing report headings, 
accounting reports, checks, or any document requiring a spe- 
cific format. USING is actually an extension of the PRINT 
statement; therefore, the same rules that apply to the PRINT 
statement also apply to the PRINT USING statement (see 


PRINT). 


Parameters: 


path 


format 


data 


Notes: 


The number corresponding to an opened device 
or file. If you do not specify path, the default 
is #1, the video screen (standard output 
device). To print to another device or file, first 
OPEN a path to that file or device (see 
OPEN). 


An expression specifying the arrangement of 
the displayed data. 


Any numeric or string constant or variable. 
Always enclose string constants within quota- 
tion marks. Each data item must be separated 
by semicolons or commas. 


Each PRINT USING format specifier begins with a single identi- 
fier letter that specifies the type of format, as shown in the fol- 


lowing table: 


Amman 


Boolean format 
exponential format 
hexadecimal format 
integer format 

real format 

string format 
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Follow the identifier letter with a constant number that specifies 
the field width. This number indicates the exact number of print 
columns the output occupies. It must allow for both the data and 
any overhead characters, such as sign characters, decimal points, 
exponents, and so on. 


Optionally, you can add a justification indicator to the format 
expression. The indicators are <, >, and *. The meaning of these 
indicators varies, depending on the format type in which you use 
them. See the format type descriptions for specific information. 


Note: Do not use any spaces within format expressions. 
The following are the format type descriptions: 
Real 


_ Use this format for real, integer, or byte type numbers. The total 
field width specification must include two overhead positions for 
the sign and decimal point. The field width has two parts, sepa- 
rated by a period. The first part specifies the integer portion of 
the field. The second part specifies how many fractional digits to 
display to the right of the decimal point. 


If a number has more significant digits than the field allows, 
BASICO9 uses the undisplayed digits to round the number 
within the correct field width. 


The justification modes are: 


< Left justify with leading sign and trailing spaces. This is 
the default if you omit a justification indicator. 


> Right justify with leading spaces and sign. 


a Right justify with leading spaces and trailing sign 
(financial format). 


Some examples and their results are: 


PRINT USING “RS. 2<", 5678. 123 so 7S. be 
PROAT. USING “Re.22".567/5.123 "6/82 
PRIN] OSING *REc2e" 12.3 Zee 
PREM USING “RE. 29". +5559 +S so" 


PRINT USING “R1@.2°".=6722.4599 6722.46- 
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Exponential 


Use this format to display real, integer, or byte values in the sci- 
entific notation format—using a mantissa and decimal exponent. 
The field has two parts: the first part must allow for six overhead 
positions for the mantissa sign, decimal point, and exponent 
characters. 


The justification modes are: 


< Left justify with leading sign and trailing spaces. This is 
the default if you omit a justification indicator. 


> Right justify with leading spaces and sign. 


Some examples and their results are: 


PRINT USING. “E12. 3"; 1234.367 1, 235E +83 

PRINT USING "E13.6>",-.001234 -1.234000E-03 

PRINT USING: "£16.59", 123456769 1,23457E+98 
Integer 


Use this format to display integer, byte, or real type numbers in 
an integer or byte format. The field width must allow for one 
position of overhead for the sign. 


The justification modes are: 


< Left justify with leading sign and trailing spaces. This is 
the default if you omit a justification indicator. 


> Right justify with leading spaces and sign. 
. Right justify with leading sign and zeroes. 
Some examples and their results are: 


PRINT USING *14<" 18 10 
FRING USING “Las” 218 10 
PRINT USinG. “14-18. =279 


Hexadecimal 


Use this format to display any data type in hexadecimal nota- 
tion. The field width specification determines the number of 
hexadecimal characters BASICO9 displays. If the data to display 
is string type, this function displays the ASCII value of each 
character in hexadecimal. 
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The justification modes are: 


< Left justify with trailing spaces. This is the default if 
you omit a justification indicator. 


> Right justify with leading spaces. 
* Center digits. 


The number of bytes of memory used to represent data varies 
according to data type. The following chart suggests field widths 
for specific data types: 


Memory Field Width 
Type Bytes To Specify 
Boolean and Byte 1 Z 
Integer 2 4 
Real 5 10 
String 1 per 2 times the string 
character length 


Some examples and their results are: 


PRINT USING “H4" 196 0064 
PRET USiNG: “Hat* =] Pree 
PRINT USING "H8“", "ABC" 414243 


String 


Use this format to display string data of any length. The field 
width specifies the total field size. If the string to display is 
shorter than the field size, PRINT USING pads it with spaces 
according to the justification mode. If the string to display is 
longer than the specified field width, PRINT USING truncates 
the right portion of the string. 


The justification modes are: 


< Left justify with trailing spaces. This is the default if 
you omit a justification indicator. 


> Right justify with leading spaces. 


a Center characters. 
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Some examples and their results are: 


PRINT USING “S9<","HELLO” HELLO 

PRINT USING "S9>","HELLO”™ HELLO 

PRINT USING ™“S9*", “HELLO” HELLO 
Boolean 


Use this format to display Boolean expression results. BASICO9 
converts the result of the expression to the strings “True” or 
“False.” The format and results are identical to STRING formats. 
The justification modes are: 


< Left justify with trailing spaces. This is the default if 
you omit a justification indicator. 


> Right justify with leading spaces. 
« — Center characters. 
If A=5 and B=6, some examples and their results are: 


PRINT USING “Bet A<B True 
PRINT USING “BS2", AS False 
PRINT USENG- "BS*". A285 False 


Control Specifiers 


You can also use control specifiers within PRINT USING for- 
mats. The three specifiers are: 


Tn Tab. n specifies a tab column at which to display 
the next data. 

Xn Spaces. n specifies a number of spaces to insert. 

‘text Constant string. text is a string that is constant to 
the format. 


An example and its result is: 


PRINT USING "’Address’ ,X1,H4,X4, ‘Data’ ,X1,He", 
1000,1080 


Address @3E8 Data 64 
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Repeat 


You can repeat identical sequences of specifications using paren- 
theses within a format specification. Enclose the group of speci- 
fications you wish to repeat, preceded by a repetition count, such 
as: 


"2€X2,r10.5)" in place of "X2,R10.5,X2,R10.5" 


“2CT242€%1 59499" In place of "12.%1,54,%1 484, 12,X1, 
245,414,854" 


Sample Program: 


This program looks at memory locations 32000 to 32010 and dis- 
plays their contents in decimal, hexadecimal, and binary. PRINT 
USING formats the display in columns. 


PROCEDURE memlook 

UDIM NUMBER,T,MEM,VALUE: INTEGER 

UDIM X,NUM: INTEGER; CHARACTER,BI:STRING 
LUPRINT "OAddr .QDec.QHex.0BinZLLUASCII" 
UFOR Z=32008 TO 320190 

(JBI = '008 

UINUMBER=PEEKC2Z) 

HIF NUMBER>@ THEN 

UIGOSUB 1809 

HENDIEF 

HIF PEEKCZ)<32 THEN 

LICHARACTER="" 

ELSE 

NCHARACTER=CHR$CPEEK(Z)) 

LIENDIF 

DIF PEEKCZ)>@ THEN 

UIPRINT USING LOR 4 17 51 Se XS. H4<, %15S8*,X2S551 "52. 
PEEKCZ),PEEKCZ),BI,CHARACTER 

WJELSE PRINT USING "Let. 174 14*,%25H4¢.% 1,86). X2, 
Si s250.80,"0900"," 

DENDIF 

LINEXT Z 

LIEND 
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189@0UNUM=L0OG18CNUMBER)/.3 
UNUM=2*NUM 

UREPEAT 

UX =NUMBER/NUM 

DIF X>2@ THEN Ble=B]4™1™ 
UNUMBER=MODCNUMBER , NUM) 
VELSE BileBlL?"a™ 

LENDIF 

UNUM=NUM/2 

OUNTIL NUM<=1 


HIF NUMBER>@ THEN 
UBl=Bie't™ 
VELSE Bl=Bi+"e” 
END Le 


URETURN 
LEND 
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P UT Writes to a direct access file 


Syntax: PUT #path,data 


Function: Writes a fixed-size binary data record to a file or 
device. Use PUT to store data in random access files. 


Although you usually use PUT with files, you can also use it 
to send data to a device. 


For information about storing data in random access files, see 
Chapter 8, “Disk Files”. Also, see GET, SEEK, and SIZE. 


Parameters: 
path A variable name you chose to use in an OPEN 
or CREATE statement that stores the number 
of the path to the file or device to which you 
are directing data. 
data Kither a variable containing the data you 
want to send or a string of data. 
Examples: 


PUT #PATH,DATA$ 
PUT INPUT ,ARRAY$ 


Sample Program: 


This procedure is a simple inventory data base. You type in the 
information for an item name, list cost, actual cost, and quan- 
tity. Using PUT, the procedure stores data in a file named 
Inventory. 


PROCEDURE inventory 

UTYPE INV_ITEM=NAME:STRING(L25]; LIST,COST:REAL; 
QTY: INTEGER 

JIDIM INV__ARRAYC108):INV_ITEM 

UDIM WORK__REC: INV_ITEM 

DIM PATH:BYTE 

HON ERROR GOTO 18 


11-129 


BASIC09 Reference 


ODELETE “inventory” 

1800N ERROR 

DCREATE #PATH,"inventory"™ 
UWORK__REC.NAME="""" 
OWORK__REC.LIST=9 
OWORK__REC.COST=90 
DOWORK__REC.QTY=@ 

OFOR N=1 TO 100 

OPUT #PATH,WORK__REC 
ONEXT N 

OLOOP 

DINPUT “Record number? ",recnum 
OIF recnum<1 OR recnum>1@@ THEN 
OPRINT 

OPRINT “End of Session" 

OPRINT 

OCLOSE #PATH 

DEND 

DENDIF 

OINPUT "Item name? ",WORK__REC.NAME 
OINPUT “List price? ",WORK_REC.LIST 
OINPUT “Cost price? ™,WORK_REC.COST 
OINPUT “Quantity? "™,WORK_REC.QTY 
OSEEK #PATH,Crecnum-1)*SIZECWORK_REC) 
OPUT #PATH,WORK__REC 

DENDLOOP 

END 
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RAD Returns trigonometric calculations in 
radians 


Syntax: RAD 


Function: Set a procedure’s state flag so that a procedure uses 
radians in SIN, COS, TAN, ACS, ASN, and ATN functions. 
Because this is the BASICO9 default, you do not need to use 
the RAD statement unless you previously used a DEG state- 
ment in the procedure. 


Parameters: None 


Examples: 
RAD 


Sample Program: 


This program calculates sine, cosine, and tangent for a value you 
supply. It calculates one set of results in degrees, using DEG, 
and the second set of results in radians using RAD. 


PROCEDURE trigcalc 
UDIM ANGLE:REAL 


LIDEG 

UINPUT “Enter the angle of two sides of a 
triangle sa.” ANGLE 

UPRINT 


PR IRT “LOCCAnte bet." StNe” COSINE”, "Tan 
OPRINT “(UDU---------------------------------- 


UPRINT “Degrees = "; ANGLE,SINCANGLE),COSCANGLE), 
TANCANGLE 9 

URAD 

UPRINT “Radians = "; ANGLE,SINCANGLE),COSCANGLE), 
TANCANGLE ) 

UPRINT 

END 
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RE AD Reads data from a device or DATA 


statement 


Syntax: READ [#path,] varname 


Function: Reads either an ASCII record from a sequential file 


or device, or an item from a DATA statement. 
Parameters: 
path A variable containing the path number of the 
file you want to access. You can also specify 
one of the standard I/O paths (0, 1, or 2). 
varname The variable in which you want to store the 
data read from a file, device, or DATA line. 
Notes: 
The following information deals with reading sequential disk 
files: 
@ To read file records, you must first dimension a variable to 


contain the path number of the file, then use OPEN or 
CREATE to open a file in the READ or UPDATE access 
mode. The command begins reading records at the first 
record in the file. After it reads each item, it updates the 
pointer to the next item. 


Records can be of any length within a file. Make sure the 
variable you use to store the records is dimensioned large 
enough to store each item. If the variable storage is too 
small, BASICO9 truncates the record to the maximum size 
for which you dimensioned the variable. If you do not indi- 
cate a variable size with the DIM statement, the default is 
32 characters. 


BASICO9 separates individual data items in the input 
record with ASCII null characters. You can also separate 
numeric items with comma or space character delimiters. 
Each input record is terminated by a carriage return 
character. 
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The following information deals with reading DATA items: 


@ READ accesses DATA line items sequentially. Each string 
a type item in a DATA line must be surrounded by quotation 
marks. Items in a DATA line must be separated with 

commas. 


@ Each READ command copies an item into the specified 
variable storage and updates the data pointer to the next 
item, if any. 


@ You can independently move the pointer to a selected DATA 
statement. To do this, use line numbers with the DATA 
lines See the DATA and RESTORE commands for more 
information on using this function of READ. 

Examples: 
READ #PATH,DATA 
READ #1,RESPONSE$ 


BEAD # INPUT, [NDEXCX 


FOR T=1 TO 18 

READ NAMES$CT) 

NEAT T 

Date oD sO Ue TENA WENDY 

Date. “SeEL™ MICKIE’ 4" P RED." MARV» WINN DE 
rf 
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Sample Program: 


This procedure puts random values between 1 and 10 into a disk 
file, then READS the values and uses asterisks to indicate how 
many times RND selected each value. 


PROCEDURE randlist 
OUDIM SHOW,BUCKET:STRING 
DIM T,PATH,SELECTC18),R: INTEGER 


BUCKET He eR HHH KKH HEHEHE HEHEHE HEHEHE HEN 
UFOR T=1 TO 10 

USELECTCT)=@ 

ONEXT T 

DON ERROR GOTO 19 

USHELL “DEL -RANDF PLE: 

18U0N ERROR 

DCREATE #PATH,"randfile™:UPDATE 
UFOR T=1 TO 108 

UR=RNDC9)+1 

OWRITE #PATH,R 

NEAT. T 

OPRINT “Random Distribution” 
OSEEK #PATH,@ 

UFOR T=1 TO 100 

OREAD #PATH,NUM 
OSELECTCNUM)=SELECTCNUM) +1 

ONEXT T 

LIFOR T=1 TO 18 

OUSHOW=RIGHT$CBUCKET ,SELECTCT)) 

PRINT USING “S6<, [3¢.S2<,s20<" “Number”; 
tao 2". SRR 

UINEX TT 

OCLOSE #PATH 

LEND 
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REM Inserts remarks in a procedure 


Syntax: REM [text] 
(* [text][*)] 


Function: Inserts remarks inside a procedure. BASICO9 
ignores these remarks; they serve only to document a proce- 
dure and its functions. Use remarks to title a procedure, show 
its creation date, show the name of the programmer, or to 
explain particular features and operations of a procedure. 


Parameters: 
text Comments you want to include within a 
procedure 
Notes: 


® You can insert remarks at any point in a procedure. 


@ The second form of REM, using parentheses and asterisks, 
is compatible with Pascal programming structure. 


@ When editing programs, you can use the exclamation char- 
acter “!” in place of the keyword REM. 


@ BASIC09’s initial compilation retains remarks, but the 
PACK compile command strips them from procedures. 
Examples: 
REM this is a comment 


C* Insert text between parentheses and 
asterisks*) 


C* or use only one parenthesis and asterisk 
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Sample Program: 


This procedure uses the various forms of REM to explain its 
operations. 


PROCEDURE copydir 

OREM Use this program with the 
L(+ GET sample program to +*) 

L(+ create a file of directory+) 
L(+ filenames, then copy the*) 
[(+ files to another directory#) 

CIDIM PATH, T,COUNT: INTEGER; FILE, JOB,DIRNAME:STRING 

KIOPEN #PATH,"dirfile":READ (* open the file 

KIINPUT "Name of new directory...",DIRNAME (# get the directory 
DSHELL "MAKDIR "+DIRNAME (# create a newdirectory 

LISHELL "LOAD COPY" 


KIWHILE NOTCEOFC#PATH)) DO 


LIREAD #PATH, FILE (* get a filename 


CJOB=FILE+" "+DIRNAME+"/"+FILE (# create the COPY syntax 
LION ERROR GOTO 10 

LIPRINT "COPY "; JOB (* display the operation 

LISHELL "COPY "+JOB (# copy the file 

18LJ0N ERROR 

LIENDWHILE 

OCLOSE #PATH 

LIEND 
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REPEAT/UNTIL 


Establishes a loop/Terminates on specified condition 


Syntax: REPEAT 
procedure lines 
UNTIL expression 


Function: Establishes a loop that executes the encompassed 
procedure lines until the result of the expression following 
UNTIL is true. Because the loop is tested at the bottom, the 
lines within the loop are executed at least once. 


Parameters: 
expression A Boolean expression (returns either True or 
False). 
procedure Statements you want to repeat until expression 
lines returns False. 
Examples: 
REPEAT 


COUNT = COUNT+1 
UNTIL COUNT > 1808 


INPUT -X 5 ¥ 

REPEAT 

X = X-1 

¥ 2 ¥=7 

UNTIL x*<1 OR Y<P 
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Sample Program: 


The procedure sorts a disk file. In this case, it is written to sort 
the diskfile created by the GET sample program—a directory 
listing. It uses a REPEAT/UNTIL loop to compare a string in 
the file with the first string in the file. If the first string is 
greater than the comparison string, the procedure swaps them. 


PROCEDURE dirsort 

DIM BIrEMP:BOGLEANs. TEMP ,FILESCT2S) =STRINGs TOP, 
BOTTOM,M,N: INTEGER 

DIM T,X,PATH: INTEGER 

UFGR T=? TO F2s 

PE LLESeT a=" 


REAL. 


UT =@ 


CUOPEN #PATH, “oirt rie sKEAD 


PRINT “LOADING: 


OWHILE NOTCEOFC#PATH)) DO 
T=T+1 

READ #PATH,FILESCT) 
OENDWHILE 

OTOP=T 

OBOTTOM=1 

OPRINT "SORTING: "; 


18UN=BOTTOM 

LUM=TOP 

UPR INE es 

ULOOP 

REPEAT 

DBTEMP=F ILESCNI<FILESCTOP? 
LIN=N+1 

HUNTIL NOTCBTEMP) 
UN=N-1 

HEXITIF N=M THEN 
UENDEXIT 


LUITEMP#FILESCM) 
UF PLES CM Jer ILESCND 
UFILESCN)=TEMP 
LIN=N +1 

UEXITIF N*M THEN 


UENDEXIT 
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UENDLOOP 

LIF N<>TOP THEN 

ULE FILESCNd<>F TLESCTOPD THEN 
UTEMP=SF TLESCN? 

JF ILESCND =F ILESCTOP) 

UF LLESC TOP) =TEMP 

UENDIF 

JENDIF 


UIF BOTTOM<N-1 THEN 
UTOP=N-1 

UGOTO 18 

END: 

ULE Nee OP THEN 
UBOTTOM=N+1 

UGOTO 10 

DEADI F 

UCLOSE #PATH 

UPELETE ““dirtile™ 
UICREATE #PATH,"“dirfile™:WRITE 
LPRINT 

UFUR 2%) ToT 

UWRITE #PATH,FILESCZ) 
HPRINT FILESCZ). 

URE XT 2 


UCLOSE #PATH 
UEND 
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RESTORE Resets READ pointer 


Syntax: RESTORE linenumber 


Function: Sets the pointer for the READ command to the 
specified line number. RESTORE without a line number sets 
the data pointer to the first data statement in the procedure. 


READ assigns the items in a DATA statement to variable 
storage. When you read an item, the pointer automatically 
advances to the next item. Using RESTORE you can skip 
backward or forward to data items at a specific line number. 


Parameters: 
linenumber The line number of the DATA items you want 
READ to access next. 
Examples: 


RESTORE: 180 


Sample Program: 


This procedure draws a box on the screen. It uses RESTORE to 
repeat the data in line 20 to create the sides of the box. 


PROCEDURE box 

DDIM: LINE 2S TRING 

UREAD LINE 

PRINT 2DNE 

FOR T=4 70 19 

URESTORE 20 

DREAD LINE 

WPRIST. DAE 

UINEXT 7 

URESTORE 18 

JREAD LINE 

PRIA LENE 

1SGDATA A+ S83 eee See Sere aes ae 
290DATA ™QUOOUOCU0UCOUCCUCUUOOo" 
UEND 


RS EST EEL LEAST 
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RE TURN Returns from subroutine 


Syntax: RETURN 


Function: Returns procedure execution to the line immedi- 
ately following the last GOSUB statement. 


Every subroutine you access with GOSUB must contain a 
RETURN statement. You can call a subroutine in this man- 
ner aS many times as you want. 


Parameters: None 


Sample Program: 


This procedure draws a design of asterisks down the display 
screen. It uses MOD to send execution to a series of PRINT 
USING routines over and over. Each PRINT USING routine 
sends execution back to the main routine with a RETURN 
statement. 


PROCEDURE stars 

UDIM T:INTEGER 

USHELL. “TMODE =PAUSE” 

UFOR T=1 TO 100 

JON MODCT,8)+1 GOSUB 18,280,30,40,50,60,70,80 
UNEXT T 

SHELL “TMDDE PAUSE"™ 

WIEND 

1BUPRINT USING “S1tg*"."e™ \- RETURN 

2OUIPRINT USING “S1Oe%. "ae \ RETURN 

SOUPRINT USING “Sig, "eee" ) RETURN 
SQUPRINT USING “STG*", “eee” \ RETURN 
SBLUPRINT USING “S194 ,“steee™ \% RETURN 
SBUPRINT USTNG “S10*" “sees \. RETURN 
JOICRINT USING “SITUS. "eee \ RETURN 
SULUPRINT USING *S104"."ee"-% RETURN 
END 
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RIGHTS Returns specified rightmost portion 
of a string 


Syntax: RIGHTS(string,length) 


Function: Returns the specified number of characters from the 
right portion of the specified string. If length is the same as or 
greater than the number of characters in string, then RIGHTS 
returns all of the characters in the string. 


Parameters: 
string A sequence of string type characters or a vari- 
able containing a sequence of string type 
characters. 
length The number of characters you want to access. 
Examples: 


PRINT RLICHT SC’ ROTDOG™, 3) 


PRINT RIGHTS$CA$ ,6) 


Sample Program: 


PROCEDURE lastname 

UDIM NAMES:STRING; LASTNAME:STRING(190] 
UIPRINT “Here are the last names:" 
UFOR T=1 TO 18 

UREAD NAMES 

UPOINTER=SUBSTRC"™ "*,NAMES) 
UPOINTER=LENCNAMES)-POINTER 
ULASTNAME=RIGHT$CNAMES,POINTER) 


UPRINT LASTNAME 


UNEXT T 


DATA “Joe Blonski","Mike Marvel"™,"Hal Skeemish", 
“Tred Langly” 


UDATA "Jane Misty","“Wendy Paston",™Martha 
Upshong", "Jacqueline Rivers" 

DATA "Susy Reetmore","Wilson Creding"™ 
DEND 
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RN D Returns a random value 


Syntax: RND(number) 


Function: Returns a random real value in the following 
ranges: 


If number = 0 then range = 0 tol 
If number > 0 then range = 0 to number 


The values produced by RND are not truly random numbers, 
but occur in a predictable sequence. Specifying a number less 
than 0 begins the sequence over. 

Parameters: 


number A numeric constant, variable, or expression. 


Examples: 
PRINT RNDC5) 
PRINT RNDCA) 


PRINT RNDCA*5S) 


Sample Program: 


This procedure presents addition problems for you to solve. 
It uses RND to select two numbers between 0 and 20. 
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PROCEDURE addition 

ODIM A,B,ANSWER,C: INTEGER 
FOR T#t TH oS 

HA=RNDC28 ) 

UB=RNDC28) 

LC=A+B 

OPRINT USING “*’What iss*,132",A 
OPRINT USING "“’(UDUUU+t0’ ,13>",B 
PRINT “OE == " 

OINPUT “COOUUDLU", ANSWER 

HIF ANSWER=C THEN 

DPRINT “CORRECT” 
LIELSE 

OPRINT "WRONG" 
UENDIF 

UPRINT 

UNEXT T 


END 
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RUN Executes another procedure 


Syntax: RUN procname [(paran],param,...])] 


Function: Calls a procedure for execution, passing the speci- 
fied parameters to the called procedure. When the called pro- 
cedure ends, execution returns to the calling procedure, 
beginning at the statement following the RUN statement. 


RUN can calla procedure existing within the workspace, a 
procedure previously compiled by the PACK command, or a 
machine language procedure outside the workspace. 


Parameters: 
procname The name of the procedure to execute. The 
procname can be the literal name of the proce- 
dure to execute, or it can be a variable name 
containing the procedure name. 
param One or more parameters that the called pro- 
gram needs for execution. The parameters can 
be variables or constants, or the names of 
entire arrays or data structures. 
Notes: 
@ You can pass all types of data to a called program except 


byte type. However, you can pass byte arrays. 


If a parameter is a constant or expression, BASICO9 passes 
it by value. That is, BASICO9 evaluates the constant or 
expression and places it in temporary storage. It passes the 
address of the temporary storage location to the called pro- 
cedure. The called program can change the passed values, 
but the changes are not reflected in the calling procedure. 


If a parameter is the name of a variable, array, or data 
structure, BASICO9 passes it to the called program by ref- 
erence. That is, it passes the address of the variable storage 
to the called procedure. Thus, the value can be changed by 
the receiving procedure, and these changes are reflected in 
the calling procedure. 
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e If the procedure named by RUN is not in the workspace, 
BASICO9 looks outside the workspace. If it cannot find it 
there, it looks in the current execution directory for a disk 
file with the proper name. If the file is on disk, BASICO9 
loads and executes it, regardless of whether it is a packed 
BASICO9 program or a machine language program. 


If the program is a machine language module, BASICO9 
executes a JSR Gump to subroutine) instruction to its entry 
point and executes it as 6809 native code. The machine 
language program returns to the original calling procedure 
by executing a RTS (return from subroutine) instruction. 


e@ After you call an external procedure, and no longer need it, 
use KILL to remove it from memory to free space for other 
operations. 


@ Machine language modules return error status by setting 
the C bit of the MPU condition codes register, and by set- 
ting the B register to the appropriate error code. 


Examples: 


RUN CALCULATEC19@,20,ADD) 


RUN PRINTCTEXT$) 


Sample Program: 


Makelist creates and displays a list of fruit. Next, it asks you to 
type a word to insert. After you type and enter a new word, 
Makelist uses RUN to call a second procedure named Insert to 
look through the list and insert the new word in alphabetical 
order. After each insertion, the procedure asks for another word. 
Press only to terminate the program. 


PROCEDURE makelist 
ODIM LISTC25),NEWORD, TEMPWORD:STRING([15] 
UDIM T,EASTs INTEGER 

ULAST=19 

DPR This 2S your list sca 

OFOR T=1 TO LAST 

DREAD LISTCT) 

UPRENT LISTCT?s 

ONEXT T 

ULOOP 
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LIPRINT 

UPRINT 

UINPUT “Type a word to insert...",NEWORD 
HEXITIF NEWORD="" THEN 

LIPRINT 


WEND "I’ve ended the session at Vour PequeSst ey.” 
HENDEXIT 

URUN InsertCLIST,NEWORD,LAST) 

UPRINT 

OPRINT "This is your new list...™ 
LEFOR T=) 70 LAST 

PRINT LISTCTr? s 

ONEXT T. 

UPRINT 

HENDLOOP 

UDATA "APPLES", "BANANAS","CANTALOUPE" 
UDATA "DATES","GRAPES","LEMONS" 

DATA "MANGOS", "PEACHES", "PLUMS" 
UDATA "PEARS" 


PROCEDURE insert 

LPARAM LISTC€25),NEWORD:STRING([15] 
UIPARAM LAST: INTEGER 

UDIM TEMPWORD:STRING[15] 
UDIM T,X: INTEGER 

LIT = 1 

UWHILE NEWORD>LISTCT) DO 
UT=T+1 

HENDWHILE 

LIFOR X=T TO LAST 
UTEMPWORD=LISTCX) 
ULISTCX)=NEWORD 
UNEWORD=TEMPWORD 

LIN EEKT x 

ULAST=LAST+1 
ULISTCLAST)=NEWORD 

WEND 
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SEEK Resets the direct-access file pointer 


Syntax: SEEK #path,number 


Function: Changes the file pointer address in a disk file. The 
pointer indicates the location in a file for the next READ or 
WRITE operation. 


You usually use SEEK with random access files to move the 
pointer from one record to another, in any order. You can also 
use SEEK with sequential access files to rewind the pointer 
to the beginning of the file (to the first item or record). 


For information about storing data in random access files, see 
Chapter 8, “Disk Files.” Also see PUT, GET, and SIZE. 


Parameters: 
path A variable name you choose in which BASICO9 
stores the number of the path it opens to the WO 
file you specify. 
number The item or record number you want to access. 
If you are rewinding a sequential access file, 
specify a number of 0. 
Examples: 


SEEK #PATH,@ 
SEEK #OUTF ELE A 
SEEK #INDEX,LOCATION*SIZECINVENTORY ) 


Sample Program: 


This procedure creates a file named Test1, then writes 10 lines 

of data into it. Next, it reads the lines from the file and displays J 
them. It uses SEEK to both store and extract the lines in blocks 

of 25 characters. 
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PROCEDURE makelines 


DIM LENGTHS BY TE 


UDIM PATH:BYTE 
UGENGTHSeZs 
UIBASE 9g 

UON ERROR GOTO 18 
IBELIETES “test 1” 


1@JON ERROR 


CFOR T=8 TO 2 
UREAD LINE$ 


UPUT #PATH,LINE$ 
NEXT -F 
UCLOSE #PATH 


UrFOR 19° TO 8 STEP 


NGET #PATH,LINE 
PROS LTE 
LINEAT T 

UICLOSE #PATH 
JEND 


UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 
UDATA "This is test 


IDATA "This is test 


BASICO9 Command Reference / 11 


DIM LINE+STRINGI 25) 


USEEK #PATH,LENGTH#T 


UIOPEN #PATH,"test1":READ 


a 


SEEK #PATH;,LENGTH#T 


line 
line 
line 
line 
line 
line 
line 
line 
line 
line 


UCREATE #PATH,"test1":WRITE 


a1" 
#2" 
#3" 
#4" 
45" 
#6" 
#7" 
#8" 
#9" 
#19" 
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SGN Returns a value’s sign 


Syntax: SGN(number) 


Function: Determines whether a number’s sign is positive or 
negative. 


If number is less than 0, then SGN returns -1. If number 
equals 0, then SGN returns 0. If number if greater than 0, 
then SGN returns 1. 


Parameters: 
number The value for which you want to determine the 
sign. 
Examples: 


PRINT SGNC-22) 
PRINT SGNCA) 
PRINT SGNC44-A) 


Sample Program: 


This procedure uses SGN to create half sine waves down the 
screen. SGN tests when the SIN calculation results are positive. 
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PROCEDURE halfsine 

LIDIM FORMULA,CALCULATE,POSITION:REAL 
SHELL. “DISPLAY €c"* 
UFORMULA=CPI+2)/15 
UCALCULATE=FOQRMULA 

USHELL “TMODE -PAUSE™ 

(FOR T=8 TO 100 
LICALCULATE=CALCULATE+FORMULA 
UIPOSITION=INTCSINCCALCULATE)#*10+16) 


HIF SGNCSINCCALCULATE))>@ THEN 
UPRINT TABCPOSITION); '#" 
UENDIF 

| ee ae 8 

USHELL “"TMODE PAUSE" 

UEND 


SS SSS SSS SS 
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SHE LG Forks another shell 


Syntax: SHELL [“string’’][+“string”...][ + variable] 
[+ variable...] 


Function: Executes OS-9 commands or programs from within 
a BASICO9 procedure. Using SHELL, you can access OS-9 
functions, including multiprogramming, utilities, commands, 
terminal and input/output control, and so on. 


When you use the SHELL command, OS-9 creates a new pro- 
cess to handle the commands you provide. If you specify an 
operation, BASICO9 evaluates the expression and passes it to 
the shell for execution. If you do not specify an operation, 
BASICO9 temporarily halts, and the shell process displays 
prompts and accepts commands in the normal manner. In this 


case, press to return to BASICO9. 


When the shell process terminates, BASICO9 becomes active 
and resumes execution at the statement following the SHELL 
statement. 


Parameters: 
string Any OS-9 command or function. String con- 
stants must be enclosed in quotation marks. 
Concatenate string constants and string vari- 
ables using a plus symbol (+). 
variable Any string variable containing an OS-9 com- 


mand or function. 
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Examples: 
SHELL "COPY FILE1 FILE2" 


Shebk “COPY FILE? PiLees* 
SHELL "COPY “*rTLess™ “+ DT RNAMET 7" FILES 
Sten “LIST DOCUMENT" 


Shek "KILL “tS TRS CN? 


Sample Program: 


You must use this procedure with the GET sample program. 
Using the two programs together enables you to copy all the files 
from one directory to another directory. The GET sample pro- 
gram reads the files in a directory and stores them in a file 
named Dirfile. This procedure reads the filenames from Dirfile 
and uses SHELL to copy them to the directory you specify. 


PROCEDURE copyutil 

UDIM PATH,T,COUNT: INTEGER; FILE,JOB,DIRNAME:STRING 
HOPEN #PATH,"dirfile™:READ 

UINPUT "Name of new directory... ",DIRNAME 
USHELL "MAKDIR "+DIRNAME 

PSHELL. “LOAD COPY” 

OWHILE NOTCEOFC#PATH)) DO 

UREAD #PATH,FILE 

OJOB=FILE+" "+DIRNAME+"/"+FILE 

HON ERROR GOTO 1@ 

UPRINT “COPY "s JOB 

USHELL “CORY “+J0B 

180J0N ERROR 

HENDWHILE 

CLOSE #PATH 

WEND 
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SIN Returns the sine of a number 


Syntax: SIN(number) 


Function: Calculates the trigonometric sine of number. You 
can use the DEG or RAD commands to cause number to rep- 
resent a value in either degrees or radians. Unless you specify 
DEG, the default is radians. SIN returns a real number. 


Parameters: 
number The angle of two sides of a triangle for which 
you want to find the ratio. 
Examples: 


PRINT SINC45) 


Sample Program: 


This procedure calculates sine, cosine, and tangent values 
for a number you type. 


PROCEDURE ratiocalc 

LIDEG 

UDIM ANGLE:REAL 

UINPUT “Enter the angle of two sides of «a 


triangle.««", ANGLE 

UPRINT 

DPRINT “Angle "STNE*, “COSTNE*;"* TAN” 

(ak 0 a a a ca a 


UPRINT ANGLE ,SINCANGLE) ,COSCANGLE),TANCANGLE ) 
UPRINT 
END 
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SIZE Returns the size of a data structure 


Syntax: SIZE(variable) 


Function: Returns the size in bytes of a variable, array, or 
data structure. SIZE is especially useful with random access 
files to determine the size of records to store in a file. You can 
also use SIZE to determine the size of variable storage for 
other purposes. 


SIZE returns the size of assigned storage, not necessarily the 
size of a string. For example, if you dimension a variable for 
15 characters, and assign a 10-character string to it, SIZE 
returns 15, not 10. SIZE returns the total size of arrays. That 
is, it returns the number of elements multiplied by the size of 
the elements. 


Parameters: 
variable The variable, array, or data structure for 
which you want to find the size. 
Examples: 


RECORDLENGTH = SIZECA$) 


PRINT “YOUR NAME IS STORED IN As SIZECNAMES); 
~ CHARACTER STRING.” 


Sample Program: 


This procedure creates a simple inventory, stored in a 
file named Inventory. It uses SIZE to calculate the size 
of each element to be stored in the file, and to move 
the pointer to the beginning of each record’s storage 
space. 
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PROCEDURE inventory 

OTYPE INV__ITEM=NAME:STRING(C25]; LIST,COST:REAL; 
QTY: INTEGER 

ODIM INV__ARRAYC10@):INV_ITEM 

ODIM WORK__REC: INV_ITEM 
ODIM PATH: BYTE 

DON ERROR GOTO 18 
ODELETE “inventory” 

1900N ERROR 

OCREATE #PATH,™inventory”" 
OWORK__REC.NAME="""" 
OWORK__REC.LIST=9@ 
OWORKW__REC.COST=@ 
DWORK__REC.QTY=9 
OFOR N=1 TO 199 
OPUT #PATH,WORK__REC 
ONEXT N 

ULOOP 

OINPUT “Record number? ",recnum 
OIF recnum<1 OR recnum>109@ THEN 
OPRINT 

OPRINT “End of Session" 

OPRINT 

OCLOSE #PATH 

LEND 

DENDIF 

OINPUT "Item name? '",WORK__-REC.NAME 
CINPUT “List pricey ,WORK_REC. LIST 
OINPUT “Cost price? ™",WORK_REC.COST 
OINPUT “Quantity? ™,WORK_REC.QTY 
OSEEK #PATH,Crecnum-1)*SIZECWORK_REC ) 
OPUT #PATH,WORK__REC 

HENDLOOP 


END 


| pec SSE SS RE AY EE EE EEE EE A ES EE EE TEE TEE EE 
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SQ Returns the value of a number raised to the 
power of 2 


Syntax: SQ(number) 


Function: Calculates the value of a number raised to the 
power of 2. 


Parameters: 


number The number you want raised to the power of 2. 


Examples: 
PRINT SQC188) 


PRINT PI#SQCR) 


Sample Program: 


This procedure uses SQ in a formula that positions asterisks on 
the screen in a sine wave pattern. 


PROCEDURE sinedown 

UDIM FORMULA,CALCULATE,POSITION:REAL 
USHELL “DISPLAY @Cc™ 
LIFORMULA=CPI+2)/15 
NCALCULATE=FORMULA 

USHELL. “TMODE -PAUSE™ 

FOR T=8 TO 208 
ICALCULATE=CALCULATE+SQCFORMULA) 
UPOSITION=INTCSINCCALCULATE)*12+16) 
UPRINT TABCPOSTT LONI s. te 

NEAT 

USHELL “TMODE PAUSE” 

DEND 
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SQR/ SQRT Returns the square root of a 


number 


Syntax: SQR(number) 
SQRT(number) 


Function: Calculates the square root of a number. SQR and 
SQRT serve the same function. 


Parameters: 
number The number for which you want the square 
root. 
Examples: 


PRINT SQRC188) 


PRINT PI*SQRTCR) 


Sample Program: 


This procedure uses SQRT in a formula to position asterisks on 
the screen in a sine wave pattern. 


PROCEDURE saqrdown 
ODIM FORMULA,CALCULATE,POSITION:REAL 
OSHELL “DISPLAY @C" 

OFORMULA=PI/15 

OCALCULATE=FORMULA 

LSHELL. “TMODE =PAUSE™ 

OFOR T=8 TO 200 
OCALCULATE=CALCULATE+SQRT CFORMULA) 
OPOSITION=INTCSINCCALCULATE)#12+16) 


OPRINT TABCPOSITION); “*" 
UNEXT T 
USHELL ““TMODE PAUSE” 


LEND 


DN a aaaaaacaaaaaaacaaaaaaaacacacaaasaaaaaaacaaaaaaaaa 
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STEP Establishes the size of increments in a 
FOR loop 


Syntax: 


FOR variable = init val TO end val [STEP value] 


[procedure statements] 


NEXT variable 


Function: STEP provides an increment value in a FOR/NEXT 
loop. If you do not specify a STEP value, the loop steps in 


increments of 1. 


BASICO9 executes the lines following the FOR statement until 
it encounters a NEXT statement. Then it either increases or 
decreases the initial value by 1 (the default) or by the value 
given by STEP. If you give the loop an initial value that is 
greater than the final value, and specify a negative value for 
STEP, the loop decreases from the initial value to the end 


value. 


Parameters: 
variable 
init val 
end val 
value 


procedure 
statements 


Any legal numeric variable name. 
Any numeric constant or variable. 
Any numeric constant or variable. 


Any numeric constant or variable. 


Procedure lines you want to be executed 


within the loop. 


11-159 


BASICO09 Reference 


Examples: 


FOR COUNTER = 1 to 108 STEP .5 
PRINT COUNTER 
NEXT COUNTER 


EDR: 4 480° TO 1 STer- 4 
PRINT -x 
NEXT -X 


FOR TEST -* A TO-BO-SIEP KATE 
PRINT “leat 
NEXT TEST 


Sample Program: 


This procedure reverses the order of characters in a word or 
phrase you type. It uses STEP to decrement a counter that 
points to each character in the string in reverse order. 


PROCEDURE reverse 

ODIM PHRASE:STRING; T,BEGIN: INTEGER 
OPRINT "Type a word or phrase you want to 
reverse:"'; 

PRINT 

OINPUT PHRASE 

OBEGIN=LENCPHRASE ) 
OPRINT "This is how your phrase looks backwards:" 
OFOR T=BEGIN TO 1 STEP -1 

OPRINT MID$CPHRASE,T,1);3 

ONEXT T 

UPRINT 


LEND 
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STOP Terminates a procedure 


Syntax: STOP [“string’’] 


Function: Causes a procedure to cease execution, print the 
message “STOP Encountered’, and return control to 
BASICO9’s command mode. You can also specify additional 
text to display when BASICO9 encounters STOP. 


Use stop when you want a procedure to terminate without 
entering the DEBUG mode. 


Parameters: 

string Text to display when STOP executes. 
Examples: 

STOP “Program terminated before comoléetion.” 

IF RESPONSE = "VY" THEN STOP “Program terminated 


at your request." 
ENDIF 
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STR$ Converts numeric data to string data 


Syntax: STR$(number) 


Function: Converts a numeric type to a string type. This lets 
you display the number as a string or use string operators on 
a number. The conversion replaces the numeric values with 
the ASCII characters of the number. STR$ is the inverse of 
the VAL function. 


Parameters: 


number Any numeric-type data. 


Examples: 
PRINT STR$(1019) 


DIM I:INTEGER 
1=44 
PRINT STR$CI) 


DIM BtsyTs 
B=001 
PRINT STR$CB) 


DIM R:REAL 
R=1234.56 
PRINT STRS$CR) 


Sample Program: 


This procedure calculates an exponential value, then adds the 
necessary number of zeroes to convert it to standard notation. It 
uses STR$ to convert the number you type to a string type value 
so that it can use string functions to add the zeroes. 
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PROCEDURE bignum 

UDIM C,PLACES,B,SIGN:STRING; EX,COUNT,NEWCOUNT, 
DECIMAL: INTEGER 

UDIM NEW,ZERO,NEWEST:STRING([10@] 

NCOUNT=-1 
UZERO="@OOGGOOBOOOD0O0000000000000000000000" 
UNEW=""*" \NEWEST="" 

UINPUT “What number do you want to raise to the 
power of 147...™, NUM 

LA=NUM*%14 

UB=STR$CA) 

HEX=SUBSTRC"E",B) 


USIGN=MID$CB,EX+1,1) 


LIPLACES=RIGHT$(B,LENCB)-EX-1) 
UFOR T=1 TO LENCB) 
UC=MID$C€B,T,1) 

LiF C=". - THEN 

UDECIMAL=@ 

UGOTO 18 

BEND LF 

UDECIMAL=DECIMAL +1 

DIF C="E" THEN 100 

UNEW=NEW+C 

1OUNEXT T 
1@@UNEWCOUNT=VALCPLACES)-DECIMAL 
UINEW=NEW+LEFT$CZERO,NEWCOUNT+1 9 
FOR T=LENCNEW) TO 1 STEP -1 
UICOUNT=COUNT +1 
UINEWEST=MID$CNEW,T,1)+NEWEST 
UIF MODCCOUNT,3)=2 AND T>1 THEN 
UNEWEST="","+NEWEST 


UENDIF 

UNEAT -F 

PRINT NUM; " to the power of 14 = ": a 
PRINT “= "ss NEWEST 

DEND 
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SUBSTR Searches for specified characters in 
a string 


Syntax: SUBSTR(targetstring,searchstring) 


Function: Searches for the first occurrence of targetstring 
within searchstring and returns the numeric value of its loca- 
tion. SUBSTR counts the first character in searchstring as 
character Number 1. Therefore, if you searched for the string 
“worth” in the string “Fortworth”, SUBSTR returns a value of 
5. 


If SUBSTR cannot find targetstring, it returns a value of 0. 


Parameters: 
targetstring The group of characters you want to locate. 
searchstring The string in which you want to find 
targetstring. 
Examples: 


PRINT SUBSTRC"THREE", "ONETWOTHREEFOURFIVESIX") 


X=SUBSTRE™ “ FULLNAMES? 


Sample Program: 


This procedure selects the last name from a string con- 
taining both a first name and a last name. It uses 
SUBSTR to find the space between the two names in 
order to determine where the last name begins. 
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PROCEDURE lastname 

UDIM NAMES:STRING; LASTNAME:STRING[I10] 
UPRINT "Here are the last names:" 

FOR T=1 TO 1@ 

UREAD NAMES 

UPOINTER=SUBSTRC" '", NAMES) 
UPOINTER=LENCNAMES)-POINTER 
ULASTNAME=RIGHT$CNAMES ,POINTER) 

UIPRINT LASTNAME 

NEST 

UDATA "Joe Blonski","Mike Marvel","Hal 
Skeemish","Fred Laungly"™ 

LIDATA "Jane Misty", "Wendy Paston","Martha 
Upshong","Jacqueline Rivers" 

DATA "Susy Reetmore","Wilson Creding™ 
LIEND 


SR RETIREES ERE PEASE IE STE SD NS ESSE SRE SESE SE, ER ESS ESL SESE SS SENS SS LE SI LEER TSE ST SE i ST SI I ST EE A SEI EI EE ERO 
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SYSCALL Executes an OS-9 System Call 


Syntax: SYSCALL callcode registers 


Function: Lets you execute any OS-9 system call from 
BASICO9. Use this command to directly manipulate your sys- 
tem or data or to directly access devices. 


Be careful! Used improperly, SYSCALL can cause undesira- 
ble results—you might unintentionally format a disk or 
destroy disk or memory data. Before using SYSCALL, you 
should be familiar with assembly language programming and 
should understand the system call information in the OS-9 
Technical Reference manual. The OS-9 Technical Reference 
manual provides information about all OS-9 system calls. 


To pass required register values to the SYSCALL command, 
create a complex data structure that contains values for all 
registers. For example: 


TYPE REGISTERS=CC,A,B,DP:BYTE; X,Y,U: INTEGER 
DIM REGS: REGISTERS 
DIM CALLCODE:BYTE 


The complex data type REGISTERS contains values for all 
registers. Unless you specifically assign values to variables 
(for instance, REGS.CC, REGS.A, and REGS.B in the pre- 
vious example), they contain random values. See the TYPE 
command for further information. 


Parameters: 
callcode is the request code of the system call you wish 
to use. All system call codes are referenced in 
the OS-9 Technical Reference manual. 
registers is a list of the register entry values required 


for the system call you are using. 


Examples: see “Sample Programs.” 
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Sample Programs: 


The following programs set up a data type (REGISTERS) for the 
register variables. Before executing SYSCALL, the procedures 
store the required register entry values in the complex data 
structure REGS. The procedures also establish CALLCODE as a 
variable to hold the request code of the system call you want to 
use. 


The Writecall procedure uses the string variable TEST to store 
text that it writes to the screen through Path 0 (the standard 
output path) using System Call $8A, I$Write. Before the proce- 
dure calls I$Write, it stores the appropriate path number (0) in 
Register A. The ADDR command calculates the address of the 
variable TEST, and the LEN command determines the length of 
the variable. The procedure stores these two values in Registers 
X and Y. 


The Readcall uses System Call $8B, I$ReadLn to perform a 
function that is the opposite of Writecall. Readcall establishes 
TEST as a string variable into which it writes the characters 
you type. Because the length of TEST is restricted to ten charac- 
ters (DIM TEST:STRING[161), the terminal bell sounds if you 
attempt to type more than 10 characters. Pressing [ENTER] 
terminates the call and the procedure prints the contents of 
TEST—the characters you typed. 
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PROCEDURE WriteCall 

OTYPE REGISTERS=CC,A,B,DP:BYTE; X,Y,U: INTEGER 
(DIM REGS:REGISTERS 

ODIM PATH,CALLCODE: BYTE 

ODIM TEST:STRING(586] 

OTEST="This is a test of I$Write, System call 
S$SA.44" 

OREGS.A=9 

OREGS.X=ADDRCTEST ) 

DOREGS.Y=LENCTEST) 

OCALLCODE=$8A 

ORUN SYSCALLCCALLCODE ,REGS) 

LIPRINT 

HEND 


PROCEDURE Readcall 

OTYPE REGISTERS=CC,A,B,DP:BYTE; X,Y,U: INTEGER 
ODIM REGS:REGISTERS 

DDIM PATH,CALLCODE:BYTE 
ODIM TEST:STRING(183 
DREGS.A=8 
DREGS.X=ADDRCTEST) 
DREGS.¥=18 

OUCALLCODE=$8B 

DRUN SYSCALLCCALLCODE ,REGS) 
LIPRIN ET 

EPRINT TEST 

UEND 
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TAB Causes PRINT to jump to the specified 
column 


Syntax: TAB(number) 


Function: Causes PRINT to display the next PRINT item to 
display in the column specified by number. If the cursor is 
already past the desired tab position, BASICO9 ignores TAB. 


Use POS to determine the current cursor position when dis- 
playing characters on the screen. 


Screen display columns are numbered from 1, the leftmost col- 
umn, to a maximum of 255. The size of BASICO9 output 
buffer varies according to the stack size. 


You can also use TAB with PRINT USING statements. 


Parameters: 
number The column at which you want PRINT to 
begin. 
Examples: 


PRINT TABC28);TITLES$ 
PRINT TABCX);ITEMNUMBER; ITEM$ 


Sample Program: 


This procedure uses asterisks to simulate a sine wave on the 
screen. It uses TAB to position each asterisk in the proper 
location. 
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PROCEDURE sinewave 
UDIM FORMULA,CALCULATE,POSITION:REAL 
USHELL "DISPLAY gC" 


= 


UFORMULA=CPI+2)/15 
LICALCULATE=FORMULA 


SRE." GODE.-- PAUSE 
LFOR T=8 TO 209 


UCALCULATE=CALCULATE+SQCFORMULA) 


— 


UPOSITION#INTCSINCCALCULATE)+*#12+16) 


DPRINT TABCPOS!I TIONS 5: ee 
NEXT. 7 
DSREil. "(MODE PAUSE” 


JEND 
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TAN Returns the tangent of a value 


Syntax: TAN(number) 


Function: Calculates the trigonometric tangent of number. 
Using DEG or RAD, you can specify the measure of the angle 
(number) in either degrees or radians. Radians are the default 
units. 


Parameters: 
number The angle for which you want to find the 
tangent. 
Examples: 


PRINT TANC45) 


Sample Program: 


This procedure calculates sine, cosine, and tangent values for a 
number you type. 


PROCEDURE ratiocalc 

LIDEG 

UDIM ANGLE:REAL 

UINPUT "Enter the angle of two sides of a 


Peng bes «a sANGLE 

LIPRINT 

UPRINT “angie. "SINE"."CUSINE’ "TAN 

UPRINT "“------------------------------------------ 


UPRINT ANGLE,SINCANGLE),COSCANGLE),TANCANGLE) 
PRINT 
UEND 
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TRIMS$ Removes spaces from the end of a string 


Syntax: TRIMS§(string) 


Function: Removes any trailing spaces from the end of the 
specified string. This function is particularly useful for trim- 
ming records you recover from a random access file. 


Parameters: 
string The string or string variable from which you 
wish to remove trailing spaces. 
Examples: 


PRINT TRIM$CA$) 


GET A$,BS,C$ 
PRINT TRIM$CA$),TRIM$CBS),TRIMSCCS$) 


Sample Program: 


This program takes names you type and puts them in a 
random access disk file. Because random access files use 
the same amount of storage for each item, short names 
are padded with extra spaces. When reading the names 
back from the file, the procedure uses TRIM$ to remove 
these extra spaces. 


PROCEDURE namestor 

ODIM NAMES,TEMP1,NAMEC108):STRING[26]; FIRST,LAST: 
STRING[L15]; INITIAL: STRING[1] 
ODIM PATH,T: INTEGER 

UNAMES="""" 

HOON ERROR GOTO 19 

ODELETE “namelist" 

18J0N ERROR 

OCREATE #PATH,"namelist":UPDATE 
UFOR T=1 TO 108 

UINAMECT)="""" 

UNEXT. T 

T=@ 


Ee eA SS TE SE SE SE A I TO ELBE DI LI ICES LEE ELLIE IE ELIE LT 
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LILOOP 

LLENPUT “Fire? Namet-*,F RST 
WEXITLE FIRSTS" THEN 
OCLOSE #PATH 

GOTO 108 

HENDEXIT 


PEN POT MO fai PNET LAL 

INPUT “Last: “LAST 

LT=T +1 

UINAMECTI=FIRST+" "+INITIAL+" "+L AST 
(IPUT #PATH,NAMECT) 

USEEK #PATH,T*26 

UENDLOOP 

1@@JOPEN #PATH,"namelist"™:READ 

GP RINT %S PRINT 

UPRINT “Lastname","Firstname","Initial"™ 

REM Print underline (40 characters) 

Le ae Ai ida nee cae eC ee aE se ee a 
PRINT 

USEEK #PATH,@ 

UT=9 

WHILE NOTCEOFC#PATH)) DO 
UIGET #PATH,NAMES 
UT=T+1 
LINAMES=TRIMS$CNAMES) 

UX=SUBSTRC"™ ", NAMES) 
LIFIRST=LEFTS$CNAMES,X-1) 
UTEMP1=RIGHT$CNAMES,LENCNAMES)-X+1) 
UINITIAL=MID$CTEMP1 ,2,1) 
WLASTHRIGHTSCTEMP1T ~LENCTEMP1)=3) 
PRINT LAST, FE RST, INIT DAL 

SEEK #PATH,T*26 

HENDWHILE 

CLOSE #PATH 


END 
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TRON / TROFF Turns on/off trace function 


Syntax: TRON 
TROFF 


Function: Turns on or off the BASICO9 trace mode. When 
trace is turned on (TRON), BASICO9 decompiles and displays 
each statement in a procedure before execution. BASICO9 also 
displays the result of each expression after evaluation. This 
function lets you follow program flow and is helpful in debug- 
ging and analyzing the execution of a procedure. After the 
procedure is debugged, remove the TRON statement. 


If you want to view only a portion of a procedure’s execution, 
surround that portion with TRON and TROFF. Tracing 
begins immediately after the TRON statement and ends at 
the TROFF statement. The rest of the program executes 
normally. 


Parameters: None 


Examples: 


BS$="GOOBOOOOBOOBOHO00000"+BS 
N=1+LENCB$) 

FOR be4 TO -) STEP <1 

TRON 

N=N-4 

ACI V=VALCMID$CB$ ,N,4)) 

TROUPE 

NEXT I 
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TRUE Returns a Boolean TRUE value 


Syntax: variable=TRUE 


Function: TRUE is a Boolean function that always returns 
True. You can use TRUE and FALSE to assign values to Boo- 
lean variables. 


Parameters: 
variable The Boolean storage unit you want to set to 
True. 
Examples: 


DIM TEST:BOOLEAN 
TEST=TRUE 


Sample Program: 


This procedure asks five questions. If your answer is correct, it 
stores the Boolean value TRUE in a Boolean type variable. If 
your answer is incorrect, it stores the Boolean value FALSE in 
the variable. 


PROCEDURE quiz 

UDIM REPLY,VALUE:BOOLEAN; ANSWER:STRING[1]; 
QUESTION: STRING[8@] 

OUFOR T=1 TO 5 

UREAD QUESTION,VALUE 

UIPRINT QUESTION 

UPRINT "CT) = TRUEQOUDOODOCF) = FALSE" 

PRINT “Select. T of Fei: 

GET #1,ANSWER 

HIF ANSWER="T' THEN 

DREPLY=TRUE 

WELSE 

UREPLY=FALSE 

WENDT 

HIF REPLY=VALUE THEN 

UPRINT \ PRINT "That’s Correct...Good Show!" 
eae 
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DPRINT "Sorry, you*re wrong...Better Luck next 
time." 

DENDIF 

OPRINT \ PRINT \N PRINT 

LINEXT T 

DATA "In computer talk, CPU stands for Central 
Packaging Unit.", FALSE 

ODATA "The actual value of 64K is 65536 
bytes.”, TRUE 

ODATA “The bits in a byte are normally numbered Q 
thredon 7a", TRUE 

ODATA "BASIC@9 has four data types.™,FALSE 
UDATA "The LAND function is a Boolean type 
operator.” ,FALSE 

LEND 
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TYPE Defines a data type 


Syntax: TYPE name = typedeclar [;typedeclar{,...]] 


Function: Defines new data types (complex data structures). 
New data types are vectors (one-dimensional arrays) of previ- 
ously defined types. Structures created by TYPE differ from 
arrays in that they can consist of elements of different types, 
and BASICO9 accesses elements by field names rather than by 
an indexed position. 


Parameters: 
name The name you select for the new data type. 
typedeclar One or more type declarations, which can con- 
sist of field names, type declarations, and sub- 
scripts. Separate different types or different 
lengths of string declarations with semicolons. 
Notes: 


@ Complex data structures allow you to create data types that 
are appropriate for a specific task. You can organize, read, 
and write associated data naturally. Also, BASICO9 estab- 
lishes and defines element positions at compilation time. 
This saves time and overhead at run time because 
BASICO9 can access the elements of a data structure faster 
than it can access the elements of an array. 


@ When you define new data structures using TYPE, you can 
include any of the five existing data types (string, real, 
integer, byte, and Boolean), or you can include data struc- 
ture types that you previously defined with TYPE. This 
means that your structures can be simple or very complex, 
such as non-rectangular data lists or trees. 


@ TYPE does not create storage. You create storage using the 
DIM statement, after using TYPE. 


@ To access elements of a data structure, use the field name 
as well as any appropriate element index. 
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@ For more information on creating and using complex data 
types, see “Complex Data Types” in Chapter 6. 


Examples: 


TYPE LIBRARY=TITLE, AUTHOR, PUBLISHER: STRING AS ]3 
REFERENCES INTEGER 
DIM BOOKC500):LIBRARY 


TYPE PARTS#=ITEM,LOCATION:STRING(L2913 CAT:REAL; 
QUANTITY;INTEGER 
DIM INVENTORYC1080):PARTS 


Sample Program: 


This procedure builds an array to contain a book reference list, 
including the book title, the author’s name, the publisher, and a 
reference number. It does so by using TYPE to create a special 
data structure to store all the information for each book. 


PROCEDURE books 

LIT¥YPE LIBRARY=TITLE, AUTHOR, PUBLISHERsSTRINGI S@] ; 
REFERENCE: INTEGER 

UDIM BOOKS(198):LIBRARY 

LIT = @ 


ULOOP 
OT =T+1 

DINPUT “BOOK TITLE. ss", BT$ 
DUBOOKSCT).TITLE=BT$ 

HEXITIF BOOKSCT).TITLE="" THEN 
UGOTO 100 

DENDEXIT 

OINPUT “Book Author...",BA$ 
UBOOKSCT).AUTHOR=BA$ 

INPUT “Book: Publisner.«a "s+ BPs 
DBOOKSCT).PUBLISHER=BP$ 

OINPUT “Reference Number...'',BOOKSCT).REFERENCE 
HJENDLOOP 

1@@0FOR X=1 TO T-1 


DPRINT, BOOKSC x22 TLTLES ? 4-09 BOURSCAD nus. & 


UBDOKSCX).PUBLISHERS * » s BOOKSCA). REFERENCE 
UNEXT xX 
END 
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UN TIL Terminates a REPEAT loop on specified 
condition 


Syntax: REPEAT 
procedure lines 
UNTIL expression 


Function: Ends a REPEAT loop. REPEAT establishes a loop 
that executes the encompassed procedure lines until the 
result of the expression following UNTIL is true. Because the 
loop is tested at the bottom, the lines within the loop are exe- 
cuted at least once. 


Parameters: 
procedures Statements you want to execute in the loop. 
lines 
expression A Boolean expression (the result must be 
either True or False). 
Examples: 
REPEAT 


COUNT = COUNT+1 
UNTIL COUNT > 108 


ENPUT: Xo ¥ 

REPEAT 

| ae ll 

pe Sad 

UNTIL. X41 OR Y<O 


See REPEAT for more information. 


11-179 


BASICO09 Reference 


USING Formats PRINT output 


Syntax: PRINT [#path] USING [format,] data|;data...] 


Function: Prints data using a format you specify. This state- 
ment is especially useful for printing report headings, 
accounting reports, checks, or any document requiring a spe- 


cific format. 


USING is actually an extension of the PRINT statement. The 
same rules that apply to the PRINT statement also apply to 
the PRINT USING statement (see PRINT). 


Parameters: 


path 


format 


data 


The number to an opened device or file. If you 
do not specify path the default is #1, the video 
screen (standard output device). To print to 
another device or file, first OPEN a path to 
that file or device (see OPEN). 


An expression specifying the arrangement of 
the displayed data. 


Any numeric or string constant or variable. 
Always enclose string constants within quota- 
tion marks. Separate all data items with 
semicolons or commas. 


See PRINT USING for more information. 
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VAL Converts string data to numeric data 


Syntax: VAL(string) 


Function: Converts string-type data to numeric-type. VAL is 
the inverse of the STR$ function. It returns the real value 
represented by the characters in a string. If any character in 
the specified string is not numeric, BASICO9 returns an error. 


Parameters: 
string An ASCII string containing one or more of the 
following characters: 0123456789. + $-. 
Examples: 


PRINT VALC123) 


AS="44.66" 
PRINT VALCA$) 


Sample Program: 


This procedure calculates an exponential value, then adds the 
necessary number of zeroes to convert it to standard notation. It 
uses STR$ to convert the original number to a string, then uses 
VAL to convert the exponent into a value to determine the cor- 
rect decimal place. 


PROCEDURE bignum 
ODIM C,PLACES,B,SIGN:STRING; EX, COUNT.;NEWCOUNT, 


DECIMAL# INTEGER 


UDIM NEW,ZERO,NEWEST:STRING[190@] 

LICOUNT=-1 
NZERO="GQOOOROBB0000000000000000000000000000" 
UINEW="""= \NEWEST="" 

HINPUT “What number do you want to raise to the 
Owe OF 14% .24"* NUM 

LIA=NUM%1 4 

UB=STR$CA) 


JEA*® SUBST RO EB? 
UISIGN=MID$CB,EX+1,1) 
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DPLACES=RIGHT$C(B,LENCB)-EX-1) 
CPOR. T=1 TO LENCE) 
OC=MID$C(B,T,1) 
IF C=" THEN 
UDECIMAL=9 


UGOTO 19 
ERD EF 
ODECIMAL=DECIMAL+1 


HIF C="E" THEN 108 
UNEW=NEW+C 

1QUNEXT T 
1@@QONEWCOUNT=VALCPLACES)-DECIMAL 
UNEW=NEW+LEFT$C ZERO ,NEWCOUNT +1) 
FOR “P=LENCNEW?: TH 1 -Sier-=4 
UCOUNT=COUNT +1 
OUNEWEST=MID$CNEW,T,1)9+NEWEST 

DIF MODCCOUNT,3)=2 AND T>1 THEN 


ONEWEST=","*+NEWEST 

DENDIF 

NEXT. TE 

PRINT NUNS * 16: the cower oT T4 
PRINT **="'s- NEWEST 

DEND 
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WHILE/ D O/ E N DWHILE Establishes 


a loop 


Syntax: WHILE expression DO 
procedure lines 
ENDWHILE 


Function: Establishes a loop that executes the encompassed 
procedure lines while the result of the expression following 
WHILE is true. Because the loop is tested at the top, the 
lines within the loop are never executed unless the expression 
is true. 


Parameters: 
expression A Boolean expression (has a result of True or 
False). 
procedure Program lines to execute if the expression is 
lines true. 
Examples: 


WHILE COUNT < 12 DO 
COUNT = COUNT+1 
ENDWHILE 


Sample Program: 


You must create a file of directory names using the GET sample 
program before you can use the following procedure. Copyutil 
uses the filenames created by the GET sample program to copy a 
directory’s files to another directory you specify. You must spec- 
ify a directory name that does not exist. Copyutil uses a 
WHILE/DO/ENDWHILE loop to continue copying until BASIC09 
reaches the end of the file. 
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PROCEDURE copyutil 

ODIM PATH,T,COUNT: INTEGER; FILE,JOB,DIRNAME:STRING 
OOPEN #PATH,"dirfile"™:READ 

OINPUT "Name of new directory. s."«DIRNAME 

OSHELL "MAKDIR "+DIRNAME 

OSHELL "LOAD COPY" 

OWHILE NOTCEOFC#PATH)) DO 

OREAD #PATH,FILE 

NJOB=FILE+™ "+DIRNAME+"/"+F ILE 


= 


CON ERROR GOTO 19 
OPRINT "COPY "; JOB 
OSHELL "COPY "+J0B 
1@00N ERROR 
DENDWHILE 

OCLOSE #PATH 


UEND 
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WRITE Writes data to a sequential file or 
m device 


Syntax: WRITE [#path,] data 


Function: Writes an ASCII record to a sequential file or to a 


device. 
Parameters: 
path A variable containing the path number of the 
file or device to which you want to send data. 
Path can be one of the the standard I/O paths 
(0742 
data The data you want to send over the specified 
path. 
Notes: 
The following information deals with writing sequential disk 
files: 


@ To write file records, you must first dimension a variable to 
contain the path number of the file, then use OPEN or 
CREATE to open a file in the WRITE or UPDATE access 
mode. 


@ Records can be of any length within a file. 


® Individual data items in the input record are separated by 
ASCII null characters. You can also separate numeric items 
with comma or space character delimiters. Each input 
record is terminated by a carriage return character. 


Examples: 
om WRITE #PATH,DATAS$ 


WRITE #1,RESPONSE$ 


WRITE #OUTPUT,INDEXCX) 
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OPEN #PATH,™"namefile™:WRITE 

FOR. b=t To 72 

READ NAMES 

WRITE #PATH, NAMES 

NEXD 

CLOSE #PATH 

DATA: Mats MGR SUE se NA go Ae 

DATA "SAL." MLOKDE 4" FRED’ "MARY 3 ACNATE” 


Sample Program: 


This procedure selects 100 random values between 1 and 10. It 
uses WRITE to place the values into a disk file. Next, it reads 
the values from the file and uses asterisks to indicate how many 
times RND selected each value. 


PROCEDURE randlist 
UDIM SHOW,BUCKET:STRING 
LUDIM T;PATH,SELECTC193,R: INTEGER 


[BUCKET =" e# RRR HHH HHH HEHEHE HEH HHH HN 
FOR T=1 TO 10 

USELECTCT)=@ 

UNEXT T 

LION ERROR GOTO 198 

SHELL. “DEL. RANDEILLE™ 

18) ON ERROR 

LICREATE #PATH,“randfile™: UPDATE 
LUFOR T=1 TO 109 

UR=RNDC9) +1 

OWRITE #PATH,R 

LINEXT T 

DOPRINT "Random Distribution" 
OSEEK #PATH,@ 

UFOR T=1 TO 109 

READ #PATH,NUM 

HUSELECTCNUM)=SELECTCNUM) +1 

UNEXT T 

LIFOR T=1 TO 10 

USHOW=RIGHT$CBUCKET ,SELECTCT)) 

UPRINT USING “S6<.13¢,52¢,S20<".,"Namber™, 7 4°" 
SHOW 

UNEXT TT: 

UCLOSE #PATH 

LEND 
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XOR Returns the exclusive OR of two values 


Syntax: operand! XOR operand2 


Function: Performs the logical exclusive OR operation on two 
or more values, returning a value of either TRUE or FALSE. 


Parameters: 
operand! Boolean values or expressions (that result in 
operand2 values of True or False). 

Examples: 


PRINT A>2 XOR Bd3 


PRINT AS="YES"™ XOR BS="YES” 


Sample Program: 


This procedure lets two people type numbers until one of them 
guesses the number that the computer picks. It uses XOR to 
determine that one of the numbers typed is the correct number, 
but not both. 


PROCEDURE drawstraw 

UDIM NUM1,NUM2,R:INTEGER; A:BOOLEAN 
PRINT “This program will help you pick" 

PRINT “between two people. Choose who will be” 
UPRINT "Person 1 and who will be Person 2." 
NIPRINT "Then, enter numbers between 1 and 16" 
PRINT “when requested." 

UPRINT 

UR=RNDC10) 

1Q8UINPUT "Person 1, type a number and press 
ENTER & 2 NUM 

UINPUT "Person 2, type a number and press 
ENTER««.™",NUM2 

UA=NUM1=R XOR NUM2=R 

LIF A=FALSE THEN 

UPRINT “"Youtll have to try again..." 

LIPRINT 
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UGOTO 190 

DENDIF 

OIF NUM1=R THEN 

OPRINT "You win, Person 1" 
DENDIF 

OIF NUM2=R THEN 

DOPRINT "You win, Person 2" 
DENDIF 

OPRINT "The Number was...""3 R 
OEND 


eee ee re eee ee eee eee ——EE==_=_—_=== 
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Program Optimization 


BASIC09’s multipass compiler produces a compressed and optim- 
ized low-level I-code for execution. Compared to other BASIC lan- 
guages, BASICO9 greatly decreases both the storage space 
required for program code and the execution speed of programs. 


Because BASICO9 produces I-code at a powerful level, it can 
handle numerous MPU (micro processor unit) instructions with a 
single interpretation. Therefore, for complex programs, there is 
little performance difference between the execution of I-code and 
pure machine-language instructions. 


Most BASIC languages have to compile from text as they run, or 
search tables of tokens in order to execute code. Instead, 
BASICO9 I-code instructions contain direct references to vari- 
ables, statements, and labels. BASICO9 fully utilizes the power of 
the 6809 instruction set, as well, which is optimized for efficient 
execution of compiler-produced code. 


Because BASICO9 interprets I-code, you have a variety of entry- 
time and run-time tests and development aids. The editor reports 
syntax errors immediately when they are entered. The debugger 
lets you debug using original program source statements and 
names. The I-code interpreter performs run-time error checking 
of array structures and BASICO9 functions. 


Optimum Use of Numeric Data Types 


The following notes apply to the use of BASICO9 numeric data 
types: 


@ BASICO09 includes several different numeric representa- 
tions (real, integer, byte), and performs automatic type 
conversions between them. This means that without 
care, your code might contain expressions or loops that 
take more than ten times longer to execute than is 


necessary. 
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@ Some BASICO9 numeric operators, such as +,-,*, and /, 


and some BASIC09 control structures include versions for 
both real and integer values. Integer versions execute 
much faster and can have slightly different properties. 
For instance, integer division discards any remainder. 


Integer operations are faster because they use corre- 
sponding 6809 instructions. Using integers increases 
speed and decreases storage requirements. Integer opera- 
tions use the same symbols as real operations, but 
BASICO09 automatically selects the integer operations 
when when all operands of an expression are of byte or 
integer type. 


Type conversion takes time. Using expressions with oper- 
ands and operators of the same kind is most efficient. 


BASICO09’s real (floating point) math provides excellent 
performance. It includes a 40-bit binary floating point 
representation and uses the CORDIC technique to derive 
all transcendental functions. This integer shift-and-add 
technique is faster and more consistent than the common 
series-expansion approximations. 


At times, you can obtain similar or identical results in a 
number of different ways and at different execution 
speeds. For example, if the variable Value is an integer, 
then Value*2 is a fast integer operation. However, if the 
expression is Value+2.9, 2.0 is represented as a real 
number and the operation requires real multiplication. 
BASICO9 must transform the integer Value into a real 
value. If the result of the expression is assigned to an 
integer type variable, BASICO9 must transform the 
result back to an integer type. The decimal point can 
slow the operation by about ten times. 
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Arithmetic Functions Ranked by Speed 
Typical Speed 


Operation in MPU Cycles 
Integer add or subtract 150 
Integer multiply 240 
Real add 440 
Real subtract 540 
Integer divide 960 
Real multiply 990 
Real divide 3870 
Real square root 7360 
Real logarithm or exponential 20400 
Real sine or cosine 32500 
Real power 39200 


Referring to the previous table can help you in your program- 
ming. For instance, notice that it is quicker to add a value to 
itself rather than multiplying it by 2. Similarly, multiplying a 
value by itself or using SQ on a value is much faster than rais- 
ing a value to the power of 2. 


Notice that a real divide takes 3870 cycles, while a real multipli- 
cation takes only 990 cycles. Multiplying a value by 0.5 is four 
times quicker than dividing the value by 2. 


Quicker Loops 


BASICO9 has two versions of FOR/NEXT loops, one for integer 
loop counter variables and one for real loop counter variables. It 
automatically uses the appropriate version. Integer FOR/NEXT 
loops are much faster than real FOR/NEXT loops. 


Other kinds of loops also run faster if you use integer type vari- 
ables for the loop counters. When writing program loops, remem- 
ber that statements inside the loop can execute many times for 
each execution outside the loop. Whenever possible, compute val- 
ues before entering loops. 
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Arrays and Data Structures 


The internal workings of BASICO9 use integer numbers to index 
arrays and complex data structures. This means that BASICO9 
must convert real type variable or expression subscripts before it 
can handle them. Using integer expressions for subscripts 
increases execution speed. 


Using the assignment statement LET to copy identically sized 
data structures is much faster than copying arrays or structures 
element-by-element inside a loop. 


The PACK Command 


PACK causes a second compilation of a specified procedure. 
Depending on such variables as the number of procedure com- 
ments and the inclusion of line numbers, packed procedures exe- 
cute from 10 to 30 percent faster. Line numbers cause unpacked 
procedures to run slower. 


Minimizing Constant Expressions 
and Subexpressions 


For maximum execution speed, precalculate constant expres- 
sions. For instance, x = x+5 produces the same result as x = 
x+sqrt(€18@)/2. However, the first expression requires approxi- 
mately 150 MPU cycles while the second expression requires 
11,650 MPU cycles. If you use such an expression inside a loop, 
the additional execution time is enormous. 


Input and Output 


Accessing data one line or record at a time is much faster than 
accessing it one character at a time. Also, the GET and PUT 
statements are much faster than READ and WRITE statements 
when accessing disk files. This is because GET and PUT use the 
same binary format as BASICO09’s internal operations. READ, 
WRITE, PRINT, and INPUT must perform binary-to-ASCII or 
ASCII-to-binary conversions, which take more time. 
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Error Codes 


Signal Errors 


Code 


1 
2 
3 


Meaning 


Unconditional termination 
Keyboard termination 
Keyboard interrupt 


BASICO09 Error Codes 


Code 


10 
11 
12 
13 
14 
15 
16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 
27 
28 
29 
30 
31 
32 
33 
34 
35 
36 
37 
38 
39 


Meaning 


Unrecognized symbol 

Excessive verbiage 

Illegal statement construction 

I-code overflow, need more workspace memory 
Illegal channel reference, bad path number given 
Illegal mode (read/write/update) - directory only 
Illegal number 

Illegal prefix 

Illegal operand 

Illegal operator 

Illegal record field name 

Illegal dimension 

Illegal literal 

Illegal relational 

Illegal type suffix 

Too-large dimension 

Too-large line number 

Missing assignment statement 

Missing path number 

Missing comma 

Missing dimension 

Missing DO statement 

Memory full, need more workspace memory 
Missing GOTO 

Missing left parenthesis 

Missing line reference 

Missing operand 

Missing right parenthesis 

Missing THEN statement 

Missing TO 
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Code 


40 
41 
42 
43 
ad 
45 
46 
47 
48 
49 
00 
ol 
a2 
53 
54 
at 
56 
a7 
58 
59 
60 
61 
62 
63 
64 
65 
66 
67 
68 
69 
70 
71 
72 
73 
74 
75 
76 
U7 
78 
79 
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Meaning 


Missing variable reference 
No ending quote 

Too many subscripts 
Unknown procedure 
Multiply-defined procedure 
Divide by zero 

Operand type mismatch 
String stack overflow 
Unimplemented routine 
Undefined variable 

Floating overflow 

Line with compiler error 
Value out of range for destination 
Subroutine stack overflow 
Subroutine stack underflow 
Subscript out of range 
Parameter error 

System stack overflow 

I/O type mismatch 

I/O numeric input format bad 
I/O conversion: number out of range 
Illegal input format 

I/O format repeat error 

I/O format syntax error 
Illegal path number 

Wrong number of subscripts 
Non-record-type operand 
Illegal argument 

Illegal control structure 
Unmatched control structure 
Illegal FOR variable 

Illegal expression type 
Illegal declarative statement 
Array size overflow 
Undefined line number 
Multiply-defined line number 
Multiply-defined variable 
Illegal input variable 

Seek out of range 

Missing data statement 
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Windowing and System Errors 


Code 


183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
194 
195 
196 
197 
198 
199 
200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
215 
216 
217 
218 
219 
220 
221 
223 


Meaning 


Illegal window type 

Window already defined 

Font not found 

Stack overflow 

Illegal argument 

(unused) 

Illegal coordinates 

Internal integrity check 
Buffer size is too small 
Illegal command 

Screen or window table is full 
Bad/undefined buffer number 
Illegal window definition 
Window undefined 

(unused) 

(unused) 

(unused) 

Path table full 

Illegal path number 
Interrupt polling table full 
Illegal mode 

Device table full 

Illegal module header 
Module directory full 
Memory full 

Illegal service request 
Module busy 

Boundary error 

End of file 

Returning non-allocated memory 
Non-existing segment 

No permission 

Bad path name 

Path name not found 
Segment list full 

File already exists 

Illegal block address 

Phone hangup data carrier detect lost 
Module not found 

Suicide attempt 
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Code 


224 
226 
227 
228 
229 
230 
231 
232 
233 
234 
235 
237 
238 
239 
240 
241 
242 
243 
244 
245 
246 
247 
248 
249 
250 
251 
252 
253 


Meaning 


Illegal process number 

No children, can’t wait for nonexistent child process 
Illegal SWI code 

Process aborted, signal 2 

Process table full, can’t fork a process 
Illegal parameter area 

Known module 

Incorrect module CRC 

Signal error 

Non-existent module 

Bad name 

System RAM full 

Unknown process ID 

No task number available 

Illegal unit error 

Bad sector number 

Write protected disk 

CRC error 

Read error 

Write error 

Not ready, device not ready 

Seek error 

Media full 

Wrong type, incompatible media type 
Device busy 

Disk ID change, disk changed with open files 
Record is locked out 

Non-sharable file busy 
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The Inkey Program 


Assembly Language Listing of Inkey 


An assembled version of Inkey is included on the CONFIG/ 
BASICO9 diskette. Use Inkey from BASICO9 with the RUN 


statement. 


EEKEKEEEEEEEHEHRE EER EEEESE 


* INKEY - a subroutine for BASICO9 by Robert Doggett 


* Called by: RUN INKEY(StrVar) 

' RUN INKEY(Path, StrVar) 
* INKEY determines if a key has been typed on the given path 

* (Standard Input if not specified), and if so, returns the next 
* character in the String Variable. If no key has been typed, the 


a 


Ed 


0021 
0081 


0000 87CDOOSE 


000) 496E6B6S 
0000 

0000 

0002 

0004 

0006 

0008 

000A 

0000 

OO0E 

W012 3064 


Ce: OS) © (SS S&S 


NAM 
IFP 1 
USE 
ENDC 


TYPE set 
REVS set 


mod 


InKeyNam fcs 


org 
Return  rmb 
PCount rmb 


Param]  rmb 
Length! rmb 
Parame  rmb 
Lengthe rmb 
E$Param equ 
DLZE equ 
InkeyEnt leax 


null string is returned, If a path is specified, it must be 
either type BYTE or INTEGER, 


INKEY 

/DO/DEFS/OS9DEFS 
SBRTN+OBUCT 
REENT+1 

InKeyEnd, InkeyNam, TYPE ,REVS 
»InkeyEnt,s12e 

“Inkey" 

0 Parameters 

2 Return addr of caller 
2 Num of params following 
2 1st param addr 

2 size 

2 end param addr 

2 size 

$38 

* 

Param! ,S 
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0014 £EC62 ldd Pcount,S Get parameter count 
0016 10830001 cmpd #| just one parameter? 
O01A 2727 beq InKeyed .. Yes; default path A=@ 
O01C 10830002 cmpd #2 Are there two params? 
0028 2635 bne ParamErr No, abort 

Q022 ECF804 ldd [Paramt,S] Get path number 

00825 AE66 Idx Length! ,9 

O027 301F leax RP byte variable? 

9029 2706 beq Inkey18 .. Yes; (A)=Path number 
Q02B 301F leax te Integer? 

002D 2628 bne ParamErr . No; abort 

Q02F 1F98 tfr B,A 

0031 3068 Inkey10 leax Parame,S 

$033 EEd2 InKey2@ = ldu ey length of string 

0035 AE84 Idx Q ,X addr of string 

0037 COFF ldb #$FF 

0039 £784 stb 0,X Initialize to null str 
§03B 11830002 cmpu #2 at least two-byte str? 
Q03F 2502 blo Inkey30 No 

0041 E701 stb tan put str terminator 
0043 Cod' InKey3@ = 1db #55.Ready 

0045 103F8D 0$9 1$GetStt is there any data ready? 
0048 2508 bcs Inkey3@ . No; exit 

004A 10860001 ldy # 

O04E 103F89 0$9 I$Read Read one byte 

0051 39 rts returns error status 
0052 CtF6 InkKey9@ = cmpd #ESNotRdy 

0054 2603 bne InkeyErr 

0056 39 rts (carry clear) 

9057 C638 ParamErr ldb #E$Param Parameter Error 

9059 43 InkeyErr coma 

Q05A 39 rts 

Q05B 1A6916 emod 

OO5E InkeyEnd equ t 
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ABS command 11-4 
absolute value 11-4 
accessing 
files 8-1, 10-8 
lines (editor) 4-4 - 4-5 
OS-9 commands from 
BASIC 3-7 
ACS command 11-5 
adding lines 4-10 - 4-12 
addition 7-3 - 7-4 
ADDR command 11-6 
address 
of variable 6-8, 11-6 
space 11-6 
advantages of BASICO9 14-1 - 
1-2 
ALPHA (medium-res) 9-9, 
9-13 
alphanumeric 
mode 9-10 
screen 9-9, 9-13, 9-30 
ALT key 1-6, 9-4 
AND 
command 11-8 
logical AND 
command 11-84 
operator 17-3, 7-4, 7-7 
appending 
data to files 8-3 
strings 7-6 
ARC command (high-res) 
9-50 
arccosine 11-5 
arcsine 11-10 
arctangent 11-11 
arithmetic 
function speed 12-2 
operators 7-3 
array 6-9 - 6-13 
address 11-6 
element 6-9 
index 11-12 
with random access 
files 8-9 


ASC command 11-9 
ASCII 
character value 11-18 
codes 9-1 - 9-6, 11-9 
ASN command 11-10 
assign 
variable storage 11-31 
variable values 11-78 
variables (debug) 5-3 
ATN command 11-11 
auto execution 3-8 
automatic error checking 1-4 


background color 
high-resolution 9-34 
medium-resolution 9-11 
backslash 1-6 
BAR command (high-res) 
9-52 - 9-53 
base 10 logarithm 11-83 
BASE command 11-12 - 
11-13 
BASIC09 
advantages 1-1 - 1-2 
graphics with 128K 
9-37 - 9-39 
quitting 1-5, 3-1 
starting 1-2 - 1-4 
starting windows 
from 9-39 - 9-41 
beep 9-54 
beginning debug 5-1 
BELL command (high-res) 
9-54 
binary data record 11-58 
BLNKOFF command (high- 
res) 9-55 
BLNKON command (high- 
res) 9-55 
BOLDSW command (high- 
res) 9-56 
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Boolean 
data 6-1 - 6-2, 6-5 
functions 7-10 
OR 11-106 
TRUE 11-175 - 11-176 
value 11-51 
border color (high-res) 9-58, 
9-65 
BORDER command (high- 
res) 9-58 
BOX command 9-60 - 9-61 
brace characters 1-6 
BREAK 
command (debug) 5-2 
key 1-6, 5-2 
breakpoint (debug) 5-2 
buffer 
defining 9-78 
font (high-res) 9-94 
get/put (high-res) 9-117 
group (high-res) 9-101 
pattern (high-res) 9-111 
button, joystick (medium- 
res) 9-9, 9-22 
BYE command 1-5, 3-1, 10-9, 
11-14 
byte 
data type 6-1 - 6-2 
numeric range 6-2 
retrieval from a file 8-5 
type functions 7-9 


calculate 
low-res characters 9-5 
sine 11-154 
square root 11-158 
call a shell command 10-9 
carriage return 1-7 
high-resolution 9-67 
CHAIN command 11-15 - 
11-16 
changing 
a procedure name 10-9 
color (high-res) 9-65 - 
9-66 


changing (cont’d) 
color (medium-res) 9-9 
directory 3-1, 3-7, 10-9, 
11-17, 11-19 
file pointer 11-148 
procedures 1-4 
scale (high-res) 
9-122 
text 4-7 - 4-9 
text (editor) 4-1 - 4-2 
working area (high-res) 
9-76 
character 
backslash 1-6 
blink (high-res) 
braces 1-6 
brackets 1-6 
fonts 9-43 - 9-44 
graphic 1-6 
high-resolution 9-8, 9-94 
reverse video (high- 
res) 9-120 
tilde 1-6 
underline (high-res) 
9-126 
underscore 1-6 
up arrow 1-6 
value 11-18 
vertical bar 1-6 
CHD command 3-1, 3-7, 
10-9, 11-17, 11-19 
CHX command 3-1, 3-7, 
10-9, 11-17 - 11-19 
CIRCLE 
high-resolution 9-62 
medium-resolution 9-9, 
9-15 - 9-16 
CLEAR 
high-resolution 9-64 
key 1-6 
medium resolution 9-9, 
9-17 
close a window (high-res) 
9-83 - 9-84 


9-121 - 


9-55 


CLOSE command 11-20 - 
11-21 
code 
ASCII 9-1 - 9-6, 11-9 
error 11-43, Al - A4 
COLOR 
high-resolution 9-65 
medium resolution 9-9, 
9-18, 9-19 
color 
codes (medium-res) 
9-10 - 9-11 
default 9-79 
high-resolution 9-31, 
9-109 - 9-110 
medium-resolution 9-11 
of border (high-res) 
9-58 - 9-59 
of pixel (medium-res) 
9-28 - 9-29 
of screen (medium- 
res) 9-26 
palette default 9-79 
set (medium-res) 9-18 - 
9-19 
command 
interpreter 3-1 
line storage area 3-3 
line symbols 11-2 
lines using spaces 2-2 
mode 1-3 
mode reference 10-9 
commands 
by type 10-7 
configuring (high-res) 
9-47 
debug 10-11 
drawing (high-res) 
editing 10-10 
executing OS-9 3-7 - 3-8 
font (high-res) 9-49 
quick reference 10-1 - 
10-6 


4 


system 3-l 


9-46 


Index 


commands (cont’d) 
text/cursor (high-res) 
9-48 
using wildcards 3-5 
window (high-res) 9-45 
comments in a procedure 
11-1385 - 11-136 
compile procedure 3-1, 3-8 - 
3-9, 10-9 
compiler, multipass 
compiling 
procedures 1-5 
saving space 1-2 
complement, logical 11-96 
complex 
data structure 1-2, 
8-11 - 8-12, 11-177 - 
11-178 
data types 
6-16 
compressed procedures 
concatenation 7-3 
condensed procedures 3-1 
configuring commands (high- 
res) 9-47 
constant expressions 
constants, string 6-7 
control key 1-6 
converting 
data types 6-6, 7-2 
numeric types 11-54, 
11-71, 11-162 - 11-163 
string data 11-181 - 
11-183 
copying structure elements 
6-16 
COS command 11-22 
cosine 11-22 
create 
data types 11-177 
overlay windows (high- 
res) 9-107 
procedures 2-1 
random access files 8-6 - 
8-9 
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6-1, 6-13 - 
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create (cont’d) 
sentences procedure 4-3 
sequential files 8-2 - 8-3 
windows 9-35 - 9-36 
CREATE command 8-2 - 8-3, 
8-6 - 8-7, 11-23 - 11-24 
CRRTN command (high- 
res) 9-67 
CTRL key 1-6 - 1-7 
CTRL-BREAK key 
sequence 1-6, 3-1 
CURDWN command (high- 
res) 9-68 
CURHOME command 9-69 
CURLFT command (high- 
res) 9-70 
CUROFF command (high- 
res) 9-71 
CURON command (high- 
res) 9-72 
current command line 1-7 
CURRGT command (high- 
res) 9-73 
cursor 
graphics (high-res) 9-95, 
9-119 
graphics (medium- 
res) 9-27 
invisible (high-res) 
movement 1-6, 9-67 - 
9-68, 9-74 - 9-75 
position 11-116 
CURUP command (high- 
res) 9-74 
CURXY command (high- 
res) 9-75 
CWAREA command (high-res) 
9-76 - 9-77 
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data 
changing in sequential 
file 8-4 
complex types 6-1, 
6-13 - 6-16 
constants 6-6 - 6-7 


data (cont’d) 

directory 3-7 

items 6-1 

manipulation 7-1 - 7-2 

meaning 6-1 

pointer 11-140 

reading 11-132 - 11-133 

structure 1-2, 11-177 - 
11-178, 12-2 

structure address 

to files 8-1 

type, Boolean 6-5 

type, byte 6-2 

type, conversion 7-2 

type, integer 6-3 

type, real 6-3 - 6-4 

types 6-1, 10-8, 11-177 - 
11-178, 12-1 

types, creating 11-177 - 
11-178 


11-6 


DATA command 11-25 - 
11-26 
DATE$ command 11-27 - 
11-28 
day 11-27 
deallocate 
buffer (high-res) 
9-102 
graphics memory 9-30 
windows (high-res) 
9-83 - 9-84 


9-101 - 


debug 
beginning 5-1 
breakpoint 5-2 
commands 5-2 - 5-4, 
10-11 
display procedure 65-3 
quitting 5-3 
starting 5-1, 5-4 - 5-5, 
11-112 
tracing 5-4 
debug command 


Index 


debug command (cont'd) 
DEG 5-2 
DIR 5-3 
LET 5-3 
LIST 5-3 
PRINT 5-3 
Q 5-3 
RAD 5-2 
STATE 5-3 
STEP 5-4 
TROFF 5-4 
TRON 5-4 
default colors 9-79 
DEFBUFF command (high- 
res) 9-78 
DEFCOL command (high- 
res) 9-79 
define a window (high-res) 
9-86 - 9-87 
defining string variables 6-4 
DEG command 11-29 
degrees, selecting in debug 
5-2, 11-29 
DELETE command 11-30 
delete line 1-6, 2-2 
editor 4-2 
high-resolution 9-80, 
9-92 
deleting 
procedure lines 4-6 - 4-7 
procedures 3-6 
delimiter 4-8 
in sequential files 8-2 
symbols (editor) 4-8 
DELLIN command (high- 
res) 9-80 
device path 11-104 
DIM command 11-31 - 11-32 
DIM statement 6-2, 11-31 
DIR 
command 3-1 -3-2, 10-9 
debug 5-3 
file access 8-1 


directory 
change 3-1, 3-7, 11-17, 
11-19 
data 3-7 
execution 3-7 
ROOT 3-7 
disassembled procedure 3-3 
disk file 8-1 
creation 11-23 
deletion 11-30 
display 
a formatted listing 10-9 
a window 1-6, (high- 
res) 9-123 - 9-124 
clearing (medium- 
res) 9-17 
current command 
line 1-7 
last line 1-7 
previous window 1-6 
procedure 3-1 
procedure from debug 
5-3 
procedure 
information 3-1, 10-9 
text 11-119 - 11-120 
workspace size 3-1, 10-9 
division 7-3 
remainder 11-93 
DO command 11-34 
dot, graphics (medium-res) 
9-28 - 9-29 
draw 
a circle (high-res) 
a circle (medium-res) 
9-9, 9-15 - 9-16 
a line (high-res) 
9-104 
an ellipse 9-88 - 9-89 
arcs (high-res) 9-50 - 
9-51 
command (high-res) 
9-46, 9-81 - 9-82 
pointer (high-res) 


9-62 - 


9-103 - 


9-125 
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draw (cont'd) 
pointer (medium-res) 
9-12 
lines (medium-res) 
9-24 - 9-25, 9-103 
rectangles (high-res) 
9-52 - 9-53, 9-60 - 9-61 
DWEND command (high- 
res) 9-83 - 9-84 
DWPROTSW command (high- 
res) 9-85 
DWSET command (high- 
res) 9-86 - 9-87 


edit 
compiler 3-1 
mode, entering 1-4 
pointer 4-1 
terminating 2-3 
EDIT command 3-1, 10-9 - 
10-10 
editor 4-1 - 4-9 
element 6-9 
elements 
of a structure, 
copying 6-16 
of an array 6-9 
ELLIPSE command (high- 
res) 9-88 - 9-89 
ELSE command 11-35 
END command 11-36 - 11-37 
end execution 11-14 
end-of-file 
message 1-6 
test 11-42 
ENDEXIT command 11-38 
ENDIF command 11-39 
ENDLOOP command _ 11-40 
ENDWHILE 11-41 
ENTER 
command (editor) 4-1 
in the editor 4-4 
key 1-7 


entering 
debug 5-4 - 5-5 
the edit mode 1-4 
EOF command 11-42 
equal operator 7-5 
erase 
a disk file 11-30 
procedures 3-1, 11-72 
to end of line 9-90 
to end of window 9-91 
EREOLINE command (high- 
res) 9-90 
EREOWNDW command (high- 
res) 9-91 
ERLINE command (high- 
res) 9-92 
ERR command 11-43 - 11-44 
error 
checking, automatic 1-4 
code 11-438 - 11-44, 
A-1 - A-4 
ina program line 2-2 
simulation 11-45 - 11-46 
trapping 11-97 - 11-99 
ERROR command 11-45 
escape function 1-6 
establishing a window 9-32, 
9-41, 9-86 - 9-87 
evaluating expressions 
7-2 
evaluation, order of 
operators 7-4 - 7-5 
examine 
aprocedure 4-4 
memory 11-113 
exclusive OR 11-187 - 11-188 
EXEC file access 8-1 
executable procedures 3-8 
execute 
a procedure 2-3, 3-1, 
3-8, 10-9, 
11-145 - 11-147 
an OS-9 command 3-1, 
3-7 - 3-8 


7-1 - 


execute (contd) 
modules 
procedure lines 
execution 
automatic 3-8 - 3-9 
directory change 3-1, 
3-7 
speed 1-1 
stepping 5-5 - 5-6 
stopping 11-161 
termination 11-14 
EXITIF/THEN/ENDEXIT 
commands 11-47 
exiting 
BASICO9 1-5 
debug 5-3 
EXP command 11-50 
exponent, natural 11-50 
exponentiation 7-3 
expression 7-1 


11-15 - 11-16 
11-34 


FALSE 
command 11-51 - 11-52 
value 7-7 

faster loops 12-2 

file 

listing procedures to 3-4 

path 11-104 

pointer 8-3, 8-5, 

11-148 - 11-149 
pointer, rewinding 8-11 
retrieving bytes 8-5 
writing 11-129 - 

11- 130, 11-185- 

11-186 

8-1 
accessing 8-1, 10-8 
appending data 8-3 
closing 11-20 - 11-21 
creating random 

access 8-6 - 8-9 


files 


creating sequential 8-2 - 
8-4 

creation 11-23 - 11-24 

opening 11-104 - 11-105 


Index 


files (cont'd) 
random access’ 8-5 - 
8-11 
writing to 8-3 
FILL command (high-res) 
9-93 
filled rectangles (high-res) 
9-52 - 9-53 
finding 
graphics screen (medium- 
res) 9-20 - 9-21 
lines 4-5 
fire button (medium-res) 
FIX command 11-53 
FLOAT command 11-54 
FONT command (high-res) 
9-94 
font-handling commands (high- 
res) 9-49 
fonts 9-438 - 9-44 
FOR/NEXT loops 
11-160 
FOR/NEXT/STEP 
commands 11-55 - 11-57 
foreground color 
high resolution 9-65 - 
9-66 
medium resolution 9-11, 
9-18 - 9-19 
fork a shell 11-152 - 11-1538 
to a window 9-32 
format 
medium resolution 9-10 
of screen (medium- 
res) 9-26 
of windows 9-34 
formatted procedure 3-1 
formatting 
display screen 11-180 
screen display 11-122 - 
11-127 
functions 7-7 - 7-10 
Boolean type 7-10 
byte type 7-9 
integer type 7-9 


9-22 


11-159 - 
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functions (cont'd) 
logical 7-10 
numeric type 7-9, 10-7 
real type 7-8 
string 7-10, 10-7 
trace 5-5 - 5-6 
transcendental 10-7 
GCOLR (medium-res) 9-9 
GCSET command (high- 
res) 9-95 
GET command 8-5, 11-58 
high-resolution 9-96 
GET/PUT buffer 9-78 
high-resolution 9-101 
GET/PUT commands (high- 
res) 9-47 
global symbol (editor) 4-5 
GLOC (medium-res) 9-9, 
9-20 
GOSUB/RETURN 
commands 11-61 
GPLOAD command (high- 
res) 9-98 
graphics 
characters 1-6 
cursor (high-res) 
9-119 
cursor (medium-res) 
9-9, 9-27 
high-resolution 9-31 - 
9-126 
levels 9-1 
logic functions 9-105 
low resolution 9-4 - 9-8 
medium-resolution 9-8 - 
9-30 
memory deallocate 9-30 
number of levels 1-2 
pattern (high-res) 
9-111 - 9-112 
pointer (high-res) 9-42 
screen (medium-res) 
9-26 


9-95, 


graphics (cont'd) 
screen location (medium- 
res) 9-20 - 9-21 
window 9-35 - 9-36 
with 128K 9-387 - 9-40 
greater than 7-3, 7-5 
grid format (medium-res) 
9-10 
group 
buffer (high-res) 
9-102 
number 9-78 


9-101 - 


hardware window 9-32 - 9-35 
high-resolution 9-31 - 9-126 
adapter 9-22 
characters 9-8 
colors 9-109 - 9-110 
quick reference 9-44 - 
9-49 
text 9-42 
hour 11-27 


I-Code 3-3, 12-1 
IF/THEN/ELSE loop 11-35 
IF/THEN/ELSE/ENDIF 
commands 11-63 - 11-65 
image, get (high-res) 9-98 
immortal shell 9-32 
initialize a disk file 11-23 - 
11-24 
INIZ command 9-32 - 9-33 
Inkey program B-1 - B-2 
INPUT command 8-5, 11-68 - 
11-70 
input/output 12-4 
insert 
a line (high-res) 
9-100 
text (editor) 4-1 
INSLIN command (high- 


9-99 - 


res) 9-99 - 9-100 
INT command 11-71 
integer 


constants 6-7 


Index 


integer (cont’d) 
data type 6-1, 6-2, 6-3 
functions 7-9 
numeric range 6-2 
interfacing with OS-9 1-1 
invisible cursor (high-res) 
9-71 


JOYSTK 9-9, 9-22 
jump 
to line number 11-102 - 
11-103 
to subroutine 11-100 - 
11-101 


key 
ALT 1-6, 9-4 
BREAK 1-6, 5-2 
CLEAR 1-6 
CTRL 1-6-1-7 
ENTER 1-7 
key sequence 
CTRL with other 
keys 1-6 -1-7 
SHIFT with other 
keys 1-6 
keyword 11-1 
KILL command _ 3-1, 3-6, 
10-9, 11-72 - 11-738 
KILLBUFF command (high- 
res) 9-101 
killing a procedure 3-6 


LAND command 11-74 - 
11-75 

language modules 1-5 

last line, displaying 1-7 

left brace 1-6 

left bracket 1-6 

LEFT$ command 11-76 

LEN command 11-77 

length of string variables 6-4 

less than 7-3 - 7-4, 7-5 


LET command 6-8, 11-78 - 
11-79 
debug 5-3 
LINE (medium-res) 9-9 
line 
accessing (editor) 4-5 
adding 4-10 - 4-12 
adding (editor) 4-10 
erasing 9-90 
see also line, deleting 
inserting (high-res) 
9-99 - 9-100 
jumping to 11-102 - 
11-103 
numbers 4-5 
renumbering 4-2, 4-10 
LINE command 
high-resolution 9-103 
medium-resolution 9-24 
line deleting 1-6, 2-2, 9-92 
editor 4-2 
high-resolution 9-80 
in procedures 4-6 - 4-7 
LIST command 3-1, 3-2 - 3-5, 
4-6, 10-9 
listing 
procedures 3-2 - 3-5, 
6-6, 10-9 
procedure lines 
(editor) 4-2 
toa file 3-4 
to a printer 3-4 
LNOT command 11-80 - 
11-81 
LOAD command _ 3-1, 3-6, 
10-9 
loading 
a buffer (high-res) 
BASICO9 1-2 - 1-4 
procedures 3-1, 3-6, 
10-9 
window image (high- 
res) 9-101 - 9-102 
local variable 6-7 
LOG command 11-82 


9-98 
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LOG10 command 11-83 
logarithm 11-82, 11-83 
logic comparison 6-5 
LOGIC command (high- 
res) 9-105 - 9-106 
logical 
AND 11-8, 11-74 - 
11-75 
block (file) 8-1 
complement 11-96 
functions 7-10 
NOT 11-80 - 11-81, 
11-96 
operators 7-7 
OR 11-87 - 11-88 
XOR 11-89 - 11-91 
loop 
EXITIF/ENDEXIT/ 
ENDEXIT 11-38, 
11-47 - 11-49 
FOR/NEXT 11-55, 
11-57, 11-95, 
11-159 - 11-160 
IF/THEN/ELSE/ENDIF 
11-35, 11-39, 
11-63 - 11-65 
LOOP/ENDLOOP 
11-40, 11-84 - 11-86 
REPEAT/UNTIL 
11-137 - 11-139, 
11-179 
WHILE/DO/ 
ENDWHILE 11-34, 
11-41, 11-183 - 11-184 
loop repetition 11-95 
LOR command 11-87 - 11-88 
low-resolution 9-1 - 9-7 
LXOR command 11-89 - 
11-91 


math 1-2 
medium-resolution 9-8 - 9-30 
format 9-10 - 9-11 
MEM command 1-8 - 1-4, 
3-1, 10-9 
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memory 
changing 11-116- 
11-117 
examining 11-113 - 
11-114 


in the workspace 3-1 
requesting 1-3 - 1-4 
saving 1-2 
size 1-3, 1-4 
message, end-of-file 1-6 
MID$ command 11-92 
minimizing storage 12-1 
minutes 11-27 
mistakes in program lines 
mixing data types 7-2 
MOD command 11-93 
MODE (medium-res) 9-9, 
9-26 
modes 
command 1-3 
edit 1-4 
module 
execution 11-15 
high-resolution 9-31 
medium-resolution 9-8 - 
9-9 
modulus 11-93 11-94 
month 11-27 
mouse (medium-res) 9-22 
MOVE (medium-res) 9-9, 
9-27 
move cursor 1-6 
high-resolution 9-68, 
9-70, 9-73 - 9-75 
move 
backward (editor) 4-5 
draw pointer (high- 
res) 9-125 
graphics cursor (high- 
res) 9-95 
the edit pointer 4-1 
multipass compiler 12-1 
multiplication 7-3 - 7-4 


natural exponent 11-50 
negation 7-3 
nesting order (debug) 5-3 
NEXT command 11-95 
NOT command 11-96 
not equal to 7-3, 7-4, 7-5 
NOT, logical 11-80 - 11-81 
operator 7-4, 7-7 
null constants 6-9 
numbers for lines 4-5 
numeric 
constants 6-6 
data conversion 11-162 - 
11-163 
data types 12-1 - 12-2 
functions 10-7 
type conversion 11-54, 
11-71 
type functions 7-9 


ON ERROR/GOTO 
command 11-97 - 11-99 
ON/GOSUB command 
11-100 - 11-101 
ON/GOTO command 11-102 - 
11-103 
OPEN command 8-3, 
11-104 - 11-105 
operands 7-2 
operators 7-1 
arithmetic 7-3 - 7-4 
equal 7-5 
greater than 7-5 
hierarchy of 7-4 
less than 7-5 
logical 7-7 
relational 7-5 - 7-6 
string 7-6 
types 7-3 
unequal 7-5 
OR 
command 11-106 
logical 11-87 - 11-88 
operator 7-7 


Index 


order 
of nesting (debug) 5-3 
of operators 7-4 - 7-5 
OS-9 commands 11-152 
accessing 3-7 - 3-8 
overlay windows 9-41, 9-107 - 
9-108 
OWSET command (high- 
res) 9-107 - 9-108 


PACK command 3-1, 3-8, 3-9, 
10-9, 12-4 
paint (high-res) 9-93 
PALETTE command (high- 
res) 9-109 - 9-110 
palette 
default colors 9-79 
high-resolution 9-34 - 
9-35 
registers 9-35 
PARAM command 6-8, 
11-108 - 11-111 
passing variables 6-8, 
11-108 - 11-111 
path 
input 11-68 
opening 11-104 - 11-105 
PATTERN command (high- 
res) 9-111 - 9-112 
PAUSE command. 5-5, 11-112 
PEEK command 9-20, 
11-113 - 11-114 
PI command 11-115 
pixel 9-34 
color (medium-res) 
9-28 - 9-29 
set (high-res) 9-113 - 
9-114 
plus sign 7-6 
POINT 
high-resolution 9-118 - 
9-114 
medium-resolution 9-10, 
9-28 - 9-29 
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pointer 
draw (hi-res) 9-42, 
9-125 
draw (medium-res) 
edit 4-1 
file 8-5 
graphics 9-42 
READ 11-140 
POKE command 9-20, 11-116 
POS command 11-118 
position 
graphics cursor (medium- 
res) 9-9 
of arecord ina file 8-5 
of cursor 11-118 
power of 2 11-157 
predefined windows 
9-33 
PRINT command 11-119 - 
11-120 
debug 5-3 
PRINT USING command 
11-122 - 11-128, 
11-180 - 11-182 
printer, listing files 3-4 


9-12 


9-32 - 


printing (tabs) 11-166 - 
11-167 
procedure 
changing 1-4 
comments 11-135 - 
11-136 


compilation 10-9 
compiling 1-5 
compressing 12-1 
condensing 3-1 
data size 3-2 
deleting 3-6 
disassembling 3-3 
display 3-1 
displaying information 
about 3-1 
erasing 3-1, 11-72 - 
11-73 
examining 4-4 
executing 1-5 
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procedure (cont'd) 
execution 2-3, 3-1 
grouping 1-4 
listing 3-2 - 3-3, 4-6 
loading 3-6 
renaming 3-2 
returning from 11-141 
saving 3-1, 3-5 - 3-6, 
10-9 
size 3-2 
suspending 11-112 
terminating 11-36 - 
11-37, 11-161 
tracing 11-174 
writing 2-1 - 2-2 
procedures 
executable 3-8 
executing 11-145 - 
11-147 
loading 3-1 
program 
execution termination 
1-6 
mistakes 2-2 
modular 1-1 
proportional text (high-res) 
9-115 - 9-116 
PROPSW command (high- 
res) 9-115 - 9-116 
protect window switch (high- 
res) 9-85 
PUT command 8-5, 8-6, 
9-117 - 9-118, 
11-129 - 11-130 
PUTGC command 9-119 


QUIT (medium-res) 
9-30 
quit 


9-10, 


BASICO9 1-5, 3-1 
debug 5-3 
the editor 2-3, 4-2 


RAD command 5-2, 11-131 
radians 5-2, 11-131 


Index 


random access files 8-5 - 8-11 
and arrays 8-9 - 8-11 
creating §&-6 - 8-9 

random value 11-143 - 

11-144 
range of numbers 6-2 
READ 8-4, 11-25, 11-132 - 
11-133 
file access 8-1 

read 
input 11-66 - 11-70 
pixel color (medium- 

res) 9-9 

read arecord 11-58 - 11-60 

real 
constants 6-7 
data type 6-1 - 6-4 
functions 7-8 
number conversion 

11-71 
number range 6-2 
number rounding 11-53 

record 8-2 
binary data 11-58 
position 8-5 

rectangle, drawing (high- 

res) 9-52 - 9-53, 9-60 - 
9-61 
reduce memory size 1-4 
registers palette 9-35, 9-109 - 
9-110 

relational operators 7-5 - 7-6 

relative storage area 3-3 

REM command 11-135 - 

11-136 
remainder (division) 
removing 

disk files 

procedures 
11-72 

spaces 11-172 - 11-1738 

RENAME command 3-1 

renaming procedures 3-2 

renumbering lines (editor) 

4-2, 4-10 


11-93 


11-30 
3-6, 10-9, 


REPEAT/UNTIL 
commands 11-137 - 
11-139, 11-179 
requesting memory 1-3 - 1-4 
reset file pointer 11-148 - 
11-149 
RESTORE command 11-140 
retrieving bytes from a file 
8-5 
RETURN command 11-141 
returning 
from subroutine 11-61 - 
11-62 
to OS-9 10-9 
reverse video (high-res) 9-120 
REVON command (high- 
res) 9-120 
rewind a file 8-11 
right brace 1-6 
right bracket 1-6 
RIGHT$ command 11-142 
ring bell 9-54 
RND command 11-148 - 
11-144 
ROOT directory 3-7 
rounding a real number 
11-53 
RUN command _ 3-1, 6-8, 10-9, 
11-145 - 11-147 


SAVE command 3-1, 3-5, 10-9 
saving 
a window area 9-96 - 
9-97 
graphic images (high- 
res) 9-117 - 9-118 
memory 1-2 
procedures 3-1, 3-5 
space by compiling 1-2 
SCALESW command (high- 
res) 9-121 - 9-122 
screen 
alphanumeric 9-30 
blink (high-res) 9-55 
clearing (high-res) 9-64 
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screen (cont'd) 

clearing (medium- 
res) 9-9, 9-17 

color (medium-res) 

display 11-122 

format (medium-res) 
9-26 

formatting 11-180 

location (medium-res) 
9-20 - 9-21 

resolution 9-31 

selecting (medium- 


9-26 


res) 9-13 - 9-14 
switching (medium- 
res) 9-9 
searching 
for text (editor) 4-2, 4-9 
in strings 11-164 - 
11-165 
seconds 11-27 


SEEK command 11-148 - 
11-149 
select a window 9-32 - 9-33 
SELECT command (high- 
res) 9-123 - 9-124 
selecting memory 1-3 
sending a carriage return 
9-67 
sentence-creating 
procedure 4-3 
sequential file writes 
11-185 - 11-186 
SETDPTR command (high- 
res) 9-125 
setting 
a point (medium-res) 
9-10, 9-28 - 9-29 
border color (high- 
res) 9-58 - 9-59 
color (medium-res) 9-18 
pixel (high-res) 9-113 - 
9-114 
READ pointer 11-140 
screen (medium-res) 9-9 
SGN command 11-150 - 
11-151 
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SHELL command 11-152 - 
11-153 

shell commands 10-9 

SHIFT-« key sequence 1-6 

SHIFT-BREAK key 
sequence 1-6 

SHIFT-CLEAR key 
sequence 1-6 

show text 11-119 - 11-121 

sign of a value 11-150 - 
11-151 

simulating an error 
11-46 

SIN command 11-154 

sine 11-154 

single-diménsioned array 
6-9 - 6-10 

SIZE command 11-155 - 
11-156 

size 


11-45 - 


data 3-2 

memory 1-3 

procedure 3-2 
space 

removing 11-172 - 

11-173 

saving by compiling 1-2 
spaces in command lines 2-2 
special keys 1-5-1-7 
speed 

of arithmetic 

functions 12-2 

of execution 1-1 
SQ command 11-157 
SQR/SQRT commands 
square root 11-158 
starting 

a shellin a window 9-36 

BASICO9 1-2 - 1-4 
STATE command (debug) 5-3 
statements 10-7 
status of joystick (medium- 

res) 9-22 - 9-23. 
STEP command. 5-4, 11-159 - 
11-160 


11-158 


step rate (debug) 5-4 
stepping through 
procedures 5-5 - 5-6 
STOP command 11-161 
stop program execution 1-6 
storage 
area of command 
lines 3-3 
minimization 12-1 
of variables 11-31 - 
11-33 
storing 
data 11-25 - 11-26 
in memory 11-116 - 
11-117 
STR$ command 11-162 - 
11-163 
string 
constants 6-7 
data conversion 11-181 - 
11-182 
data type 6-1 - 6-2 
functions 10-7 
length 6-4, 11-77 
operators 7-6 
storage 6-5 
variables 6-4 - 6-5 
strings 
appending 7-6 
portioning 11-76, 11-92, 
11-142 
searching 11-164 
structured programming 1-1 
structures, complex data 
8-11 - 8-15 
subroutine 
commands 11-61 - 11-62 
jumps 11-100 - 11-101 
SUBSTR command 11-164 - 
11-165 
substrings 11-92 
subtraction 7-3 - 7-4 
suspending execution 11-112 
switching screens (medium- 
res) 9-9, 9-13 - 9-14 


Index 


symbolic debugging 5-1 
syntax 11-1 
system 
commands 3-1 
interfacing 1-1 


TAB command 11-166 - 
11-167 
TAN command 11-168 
tangent 11-168 
terminating 
a procedure 11-36 - 
11-37, 11-161 
the editor 4-2 
test for end-of-file 11-42 
text 
changing 4-2, 4-7 - 4-9 
characters (high-res) 
9-94 
display 11-119 - 11-121 
fonts 9-43 - 9-44 
formatting 11-122 - 
11-128 
high-resolution 9-42 - 
9-44 
proportional 9-115 - 
9-116 
searching 4-2, 4-9 
cursor commands (high- 
res) 9-48 
three-dimension arrays 6-13 
tilde 1-6 
time 11-27 - 11-28 
tracing 
execution 5-4 - 5-6, 
11-174 
transcendental functions 10-7 
trapping errors 11-97 - 11-99 
TRIM$ command 11-172 - 
11-173 
TROFF command (debug) 
5-4, 11-174 
TRON command 5-4 - 5-6, 
11-174 
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TRUE command 11-175 - 
11-176 
turning off the cursor 9-71 
two-dimension array 6-9 
type 
conversion 6-6, 7-2 
mismatch 6-6 
of data 6-1 - 6-16, 10-8 
of file access 8-1 
of operators 7-3 
TYPE command 8-12, 
11-177 - 11-178 


underscore 1-6 

UNDLNOFF command (high- 
res) 9-126 

UNDLNON command (high- 
res) 9-126 

unequal 7-5 

UNTIL 11-1387 - 11-139, 
11-180 

up arrow 1-6 

UPDATE 8-1, 8-4 

USING command 11-180 - 
11-182 

using debug 5-4 - 5-5 


VAL command 11-181 - 
11-182 
value 
absolute 11-4 
Boolean 11-51 - 11-52 
random 11-143 - 11-144 
variable 
address 6-8, 11-6 
initialization 6-8 
local 6-7 
passing 6-8 - 6-9, 
11-108 - 11-111 
size 11-155 - 11-156 
storage 11-31 - 11-33 
value of 11-78 - 11-79 
variables 11-2 
assigning (debug) 5-3 


local 6-7 
string 6-4 - 6-5 
vector 6-13 
vertical bar 1-6 
video 
address (medium-res) 
reverse (high-res) 9-120 
visible cursor (high-res) 9-72 


WCREATE command 9-33 - 
9-34 
WHILE/DO/ENDWHILE 
loop 11-34, 11-41, 
11-180 - 11-181 
whole number, range 6-2 
wildcard 
editor 4-1 
using with commands 
3-5 
window 
area, saving 9-96 - 9-97 
commands (high-res) 
9-45 
deallocating (high- 
res) 9-83 - 9-84 
defining (high-res) 
9-86 - 9-87 
display 1-6, 9-123 - 
-124 
erasing 9-91 
establishing 9-32 - 9-41 
formats 9-34 
graphics 9-35 - 9-36 
hardware 9-32 - 9-35 
image (high-res) 9-101 - 
9-102 
overlay (high-res) 
9-107 - 9-108 
protect switch (high- 
res) 9-85 
shell 9-36 
working area (high-res) 
9-76 - 9-77 
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windows writing 
defining 9-33 - 9-34 a procedure 2-1 - 2-2 
from BASICO9 9-39 - to files 8-3, 11-129 
9-41 
overlay 9-41 XOR command 11-187 - 
predefined 9-32 - 9-33 11-188 
with high-resolution XOR operator 7-7 
9-31 


working area (high-res) 9-76 year 11-27 
workspace 1-3, 3-1 
WRITE command 11-185 - 

11-186 
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